DPF OAuth 2.1 Authorization Server API

openapi: 3.2.0
info:
  title: DPF OAuth 2.1 Authorization Server API
  version: 1.1.0
  description: '## Common error responses


    Unless otherwise noted, any authenticated endpoint may also return the following

    responses, each with the standard `ErrorResponse` body. To avoid repetition they are

    not listed individually on each operation:


    - **400 Bad Request** — malformed JSON, unknown action, or missing/invalid fields

    - **401 Unauthorized** — missing or invalid JWT bearer token

    - **402 Payment Required** — the account has insufficient credits or an inactive subscription

    - **403 Forbidden** — authenticated but not permitted (no access to the resource, or a higher access level / plan tier is required)


    Operation-specific responses (e.g. `404`, `409`) are documented on each endpoint.'
  contact:
    name: Contact DPF
    url: mailto:contact@dpf-it.com
  license:
    name: Proprietary
    url: https://dpf-it.com/#terms
servers:
- url: https://api.dpf-it.com
  description: Production API
security: []
tags:
- name: OAuth 2.1 Authorization Server
  description: 'PKCE-only OAuth 2.1 authorization server with Dynamic Client Registration (DCR) and refresh

    token rotation. Used by remote MCP clients (VS Code, Cursor, Claude, ChatGPT) to obtain a

    DPF access token via a real browser login — no password ever passes through an LLM/chat

    context. Access tokens are the same 24h user JWT issued by `/auth/login`.'
paths:
  /oauth/authorize:
    get:
      tags:
      - OAuth 2.1 Authorization Server
      summary: Authorization endpoint (hosted login page)
      description: 'Renders a real, hosted HTML login page — not a JSON API. This is where the actual login

        form lives; the password is typed here, in the browser, never inside an MCP tool call or

        chat context. PKCE (S256) is mandatory, matching OAuth 2.1. On success, redirects to

        `redirect_uri` with a short-lived, single-use `code`.'
      operationId: oauthAuthorizeGet
      parameters:
      - name: client_id
        in: query
        required: true
        schema:
          type: string
      - name: redirect_uri
        in: query
        required: true
        schema:
          type: string
        description: Must exactly match one of the client's registered redirect URIs
      - name: response_type
        in: query
        required: true
        schema:
          type: string
          enum:
          - code
      - name: code_challenge
        in: query
        required: true
        schema:
          type: string
      - name: code_challenge_method
        in: query
        required: true
        schema:
          type: string
          enum:
          - S256
      - name: state
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          description: Login page rendered (text/html)
        '400':
          description: Invalid client_id, redirect_uri, or missing/invalid PKCE parameters
    post:
      tags:
      - OAuth 2.1 Authorization Server
      summary: Login form submission
      description: 'Handles the login form''s own POST (application/x-www-form-urlencoded: email, password, plus

        the same OAuth params carried through as hidden fields). Not intended to be called directly

        by API clients — this is the target of the form rendered by GET /oauth/authorize.'
      operationId: oauthAuthorizePost
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                email:
                  type: string
                password:
                  type: string
                client_id:
                  type: string
                redirect_uri:
                  type: string
                response_type:
                  type: string
                code_challenge:
                  type: string
                code_challenge_method:
                  type: string
                state:
                  type: string
      responses:
        '302':
          description: Login succeeded — redirects to redirect_uri with ?code=...&state=...
        '200':
          description: Login failed — re-renders the login page with an error message (text/html)
  /oauth/token:
    post:
      tags:
      - OAuth 2.1 Authorization Server
      summary: Token endpoint (authorization_code, refresh_token, and client_credentials…
      description: 'Standard OAuth 2.1 token endpoint. Responses use the standard OAuth2 error shape

        (`{ error, error_description }`), not DPF''s usual `{ error: { code, message } }` envelope —

        this endpoint is consumed by generic OAuth2 clients (VS Code, Cursor, Claude), so spec

        compliance wins over internal convention here.


        **grant_type=authorization_code**: exchanges a code (from /oauth/authorize) + code_verifier

        for an access token + refresh token. Single-use — the code is burned on first use regardless

        of outcome.


        **grant_type=refresh_token**: rotates the presented refresh token (issues a new one, invalidates

        the old). Reusing an already-rotated token is treated as a theft signal and revokes the entire

        token family, forcing full re-authentication.


        **grant_type=client_credentials**: machine-to-machine auth for a confidential client

        registered via `POST /oauth/clients` (e.g. for AWS Bedrock AgentCore Gateway). No refresh

        token is issued — re-authenticate with `client_id`/`client_secret` each time. The resulting

        access token is a standard user-shaped JWT tied to whichever account created the client, so

        it works against every DPF API, the MCP server (`/mcp`), and the Iceberg REST catalog

        (`/iceberg/v1/*`) across *all* of that account''s workspaces — not just one.


        Access tokens are the same 24h user JWT issued by `/auth/login`.'
      operationId: oauthToken
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                grant_type:
                  type: string
                  enum:
                  - authorization_code
                  - refresh_token
                  - client_credentials
                code:
                  type: string
                  description: Required for authorization_code
                redirect_uri:
                  type: string
                  description: Required for authorization_code
                code_verifier:
                  type: string
                  description: Required for authorization_code (PKCE)
                refresh_token:
                  type: string
                  description: Required for refresh_token
                client_id:
                  type: string
                  required: true
                client_secret:
                  type: string
                  description: Required for client_credentials
      responses:
        '200':
          description: Token issued
          content:
            application/json:
              schema:
                type: object
                properties:
                  access_token:
                    type: string
                  refresh_token:
                    type: string
                  token_type:
                    type: string
                    example: Bearer
                  expires_in:
                    type: integer
                    example: 86400
        '400':
          description: invalid_request, invalid_grant, or unsupported_grant_type
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  error_description:
                    type: string
  /oauth/register:
    post:
      tags:
      - OAuth 2.1 Authorization Server
      summary: Dynamic Client Registration (RFC 7591)
      description: 'Lets a spec-compliant MCP client (VS Code, Cursor, Claude) self-register with zero manual

        setup on the DPF side. Only public clients (PKCE, no secret) are issued —

        `token_endpoint_auth_method` is always `none` in the response, regardless of what was

        requested, since PKCE alone is a complete, secure flow for the native/browser-based clients

        this server targets.'
      operationId: oauthRegister
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - redirect_uris
              properties:
                client_name:
                  type: string
                redirect_uris:
                  type: array
                  items:
                    type: string
      responses:
        '201':
          description: Client registered
          content:
            application/json:
              schema:
                type: object
                properties:
                  client_id:
                    type: string
                  client_name:
                    type: string
                  redirect_uris:
                    type: array
                    items:
                      type: string
                  token_endpoint_auth_method:
                    type: string
                    example: none
                  client_id_issued_at:
                    type: integer
                  grant_types:
                    type: array
                    items:
                      type: string
                  response_types:
                    type: array
                    items:
                      type: string
        '400':
          description: invalid_client_metadata or invalid_redirect_uri
  /oauth/clients:
    post:
      tags:
      - OAuth 2.1 Authorization Server
      summary: Register a confidential client (client_credentials)
      description: 'Creates a confidential OAuth client tied to the calling account, for the

        `client_credentials` grant — DPF''s recommended way to set up machine-to-machine access

        (AWS Bedrock AgentCore Gateway, CI pipelines, etc.). Unlike `/oauth/register`, this requires

        a logged-in user (`Authorization: Bearer `) and issues a `client_secret` — shown

        exactly once in the response, only its bcrypt hash is persisted. Uses DPF''s usual

        `{ success, data }` / `{ error }` envelope (not the OAuth2 error shape), since it''s a DPF

        API endpoint, not part of the OAuth2 spec surface.'
      operationId: oauthCreateClient
      security:
      - BearerAuth: []
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                client_name:
                  type: string
                  description: Defaults to 'Unnamed service client'
      responses:
        '201':
          description: Client created
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: object
                    properties:
                      clientId:
                        type: string
                      clientSecret:
                        type: string
                        description: Shown once — not recoverable afterward
                      clientName:
                        type: string
        '401':
          description: Missing/invalid Authorization header
    get:
      tags:
      - OAuth 2.1 Authorization Server
      summary: List your confidential clients
      description: Lists the caller's own confidential clients (never includes secrets/hashes).
      operationId: oauthListClients
      security:
      - BearerAuth: []
      responses:
        '200':
          description: Clients listed
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  data:
                    type: object
                    properties:
                      clients:
                        type: array
                        items:
                          type: object
                          properties:
                            clientId:
                              type: string
                            clientName:
                              type: string
                            createdAt:
                              type: integer
  /oauth/clients/revoke:
    post:
      tags:
      - OAuth 2.1 Authorization Server
      summary: Revoke a confidential client
      description: 'Deletes one of the caller''s own confidential clients, immediately invalidating its

        `client_id`/`client_secret` for future `client_credentials` exchanges (already-issued access

        tokens remain valid until their own 24h expiry). Returns `404` for both an unknown

        `client_id` and one owned by a different account — the two cases aren''t distinguished, to

        avoid leaking existence of other users'' clients.'
      operationId: oauthRevokeClient
      security:
      - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - client_id
              properties:
                client_id:
                  type: string
      responses:
        '200':
          description: Client revoked
        '404':
          description: Unknown client_id (or not owned by the caller)
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT token obtained from login or registration