openapi.yaml

openapi: 3.0.3
info:
  title: Keycast HTTP API
  version: 1.0.0
  description: |
    # Keycast HTTP Signing API

    Fast HTTP signing for Nostr events without NIP-46 relay overhead. Keycast provides both traditional NIP-46 remote signing and a high-performance HTTP API for low-latency signing operations.

    ## Authentication

    Most endpoints require a UCAN token obtained from the `/auth/login` or `/auth/register` endpoints. Include the token in the `Authorization` header:

    ```
    Authorization: Bearer <your-jwt-token>
    ```

    ## Performance

    - **Fast Path**: ~10ms signing using cached handlers (unified mode)
    - **Slow Path**: ~50-100ms signing using database + KMS decryption

    ## Security Notes

    ⚠️ **Current Limitations**:
    - No permission validation on HTTP signing endpoint
    - No rate limiting (endpoints can be called unlimited times)
    - UCAN tokens valid for 24 hours

    These limitations are being addressed in upcoming releases.

  contact:
    name: Keycast Support
    url: https://github.com/rabble/keycast
  license:
    name: MIT
servers:
  - url: https://entryway.divine.video/api
    description: Production ATProto Authorization Server
  - url: https://login.divine.video/api
    description: Production Divine and Nostr login server
  - url: http://localhost:3000/api
    description: Local development

components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: UCAN token from /auth/register or /auth/login
    ServiceToken:
      type: http
      scheme: bearer
      description: KEYCAST_SERVICE_TOKEN for trusted service-to-service callers (e.g. the AP gateway)

  schemas:
    Error:
      type: object
      properties:
        error:
          type: string
          description: Error message
        code:
          type: string
          description: Stable application error code, when available
        error_description:
          type: string
          description: Human-readable detail accompanying an RFC 6749 OAuth error code, when available
      required:
        - error

    ApCreateKeyRequest:
      type: object
      properties:
        pubkey:
          type: string
          description: Hex Nostr pubkey of the actor. For service-token callers, either pubkey or actor is required; for UCAN callers it defaults to the token's pubkey and, if present, must match it.
          example: "e1ff3bfdd4e40315959b08b4fcc8245eaa514637e1d4ec2ae166b743341be1af"
        actor:
          type: string
          description: ActivityPub actor URL. Alternative to pubkey for the gateway; resolves /ap/users/{username} against the tenant selected by the Keycast request Host.
          example: "https://divine.video/ap/users/alice"
    ApKeyResponse:
      type: object
      properties:
        pubkey:
          type: string
        public_key_pem:
          type: string
          description: SPKI PEM public key for the actor's publicKey.publicKeyPem.
          example: "-----BEGIN PUBLIC KEY-----\nMIIBIjAN...\n-----END PUBLIC KEY-----\n"
        key_type:
          type: string
          example: "rsa-2048"
        created:
          type: boolean
          description: true if a new key was minted; false if an existing key was returned (idempotent).
      required:
        - pubkey
        - public_key_pem
        - key_type
        - created
    ApPublicKeyResponse:
      type: object
      properties:
        pubkey:
          type: string
        public_key_pem:
          type: string
        key_type:
          type: string
          example: "rsa-2048"
      required:
        - pubkey
        - public_key_pem
        - key_type
    ApSignRequest:
      type: object
      properties:
        pubkey:
          type: string
          description: Hex Nostr pubkey of the actor. For service-token callers, either pubkey or actor is required.
        actor:
          type: string
          description: ActivityPub actor URL. Alternative to pubkey for the gateway; resolves /ap/users/{username} against the tenant selected by the Keycast request Host.
        signing_string:
          type: string
          description: The exact draft-cavage HTTP-Signature signing string. Signed as UTF-8 bytes.
          example: "(request-target): post /inbox\nhost: mastodon.social\ndate: Mon, 01 Jan 2026 00:00:00 GMT\ndigest: SHA-256=X..."
      required:
        - signing_string
    ApSignResponse:
      type: object
      properties:
        pubkey:
          type: string
        signature:
          type: string
          description: base64-encoded RSASSA-PKCS1-v1_5 SHA-256 signature for the Signature header.
        algorithm:
          type: string
          example: "rsa-sha256"
      required:
        - pubkey
        - signature
        - algorithm

    RegisterRequest:
      type: object
      properties:
        email:
          type: string
          format: email
          example: user@example.com
        password:
          type: string
          format: password
          minLength: 8
          example: "SecureP@ssw0rd"
        nsec:
          type: string
          description: Optional user-provided Nostr secret key (nsec or hex format). If not provided, a new key will be generated.
          example: "nsec1..."
      required:
        - email
        - password

    RegisterResponse:
      type: object
      properties:
        user_id:
          type: string
          description: User's public key (hex format)
        email:
          type: string
        pubkey:
          type: string
          description: User's Nostr public key (hex format)
        token:
          type: string
          description: UCAN authentication token
      required:
        - user_id
        - email
        - pubkey
        - token

    LoginRequest:
      type: object
      properties:
        email:
          type: string
          format: email
        password:
          type: string
          format: password
      required:
        - email
        - password

    LoginResponse:
      type: object
      properties:
        token:
          type: string
          description: UCAN authentication token
        pubkey:
          type: string
          description: User's Nostr public key (hex format)
      required:
        - token
        - pubkey

    NostrEvent:
      type: object
      description: Nostr event structure (NIP-01)
      properties:
        kind:
          type: integer
          description: Event kind number
          example: 1
        content:
          type: string
          description: Event content
          example: "Hello Nostr!"
        tags:
          type: array
          items:
            type: array
            items:
              type: string
          example: [["p", "pubkey123"], ["e", "eventid456"]]
        created_at:
          type: integer
          description: Unix timestamp
          example: 1234567890
      required:
        - kind
        - content
        - tags
        - created_at

    SignedNostrEvent:
      allOf:
        - $ref: '#/components/schemas/NostrEvent'
        - type: object
          properties:
            id:
              type: string
              description: Event ID (hex format)
            pubkey:
              type: string
              description: Author's public key (hex format)
            sig:
              type: string
              description: Schnorr signature (hex format)
          required:
            - id
            - pubkey
            - sig

    SignEventRequest:
      type: object
      properties:
        event:
          $ref: '#/components/schemas/NostrEvent'
      required:
        - event

    SignEventResponse:
      type: object
      properties:
        signed_event:
          $ref: '#/components/schemas/SignedNostrEvent'
      required:
        - signed_event

    BunkerUrlResponse:
      type: object
      properties:
        bunker_url:
          type: string
          format: uri
          description: NIP-46 bunker connection string
          example: "bunker://pubkey?relay=wss://relay.example.com&secret=xyz"
      required:
        - bunker_url

    PubkeyResponse:
      type: object
      properties:
        pubkey:
          type: string
          description: Public key in hex format
          example: "abc123..."
        npub:
          type: string
          description: Public key in bech32 format
          example: "npub1..."
      required:
        - pubkey
        - npub

    UserProfile:
      type: object
      properties:
        public_key:
          type: string
        username:
          type: string
          nullable: true
        display_name:
          type: string
          nullable: true
        avatar_url:
          type: string
          nullable: true
        email:
          type: string
        email_verified:
          type: boolean
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time

    SessionInfo:
      type: object
      properties:
        bunker_public_key:
          type: string
        application_name:
          type: string
        created_at:
          type: string
          format: date-time
        last_used_at:
          type: string
          format: date-time
          nullable: true

    AtprotoEnableRequest:
      type: object
      properties:
        username:
          type: string
          example: "alice"
      required:
        - username

    AtprotoCrosspostRequest:
      type: object
      properties:
        enabled:
          type: boolean
      required:
        - enabled

    AtprotoStatusResponse:
      type: object
      properties:
        enabled:
          type: boolean
          description: Whether future ATProto cross-publishing is enabled for this user.
        state:
          type: string
          nullable: true
          enum:
            - pending
            - ready
            - failed
            - disabled
          description: Lifecycle state for ATProto provisioning. Null means ATProto has never been enabled.
          example: "pending"
        did:
          type: string
          nullable: true
          description: PLC DID assigned to the user once provisioning reaches the ready state.
          example: "did:plc:abc123"
        error:
          type: string
          nullable: true
          description: User-visible error from the last failed provisioning attempt, if any.
        username:
          type: string
          nullable: true
          description: Claimed username associated with the ATProto lifecycle state.
          example: "alice"
      required:
        - enabled

paths:
  /auth/register:
    post:
      summary: Register new user
      description: |
        Create a new user account with email/password authentication. Automatically generates a Nostr keypair and returns a UCAN token for immediate use.

        **BYOK Support**: You can optionally provide your own Nostr secret key via the `nsec` parameter. If not provided, a new key will be generated.
      tags:
        - Authentication
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RegisterRequest'
            examples:
              basic:
                summary: Register with auto-generated key
                value:
                  email: "user@example.com"
                  password: "SecurePassword123"
              byok:
                summary: Register with your own key (BYOK)
                value:
                  email: "user@example.com"
                  password: "SecurePassword123"
                  nsec: "nsec1abc123..."
      responses:
        '200':
          description: Successfully registered
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RegisterResponse'
        '400':
          description: Invalid request (weak password, invalid nsec)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: Email already exists
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /auth/login:
    post:
      summary: Login
      description: Authenticate with email/password and receive a UCAN token valid for 24 hours.
      tags:
        - Authentication
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LoginRequest'
      responses:
        '200':
          description: Successfully authenticated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LoginResponse'
        '401':
          description: Invalid credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /user/sign:
    post:
      summary: Sign Nostr event (Fast HTTP signing)
      description: |
        Sign a Nostr event via HTTP - **10-50x faster than NIP-46**.

        ## Performance
        - **Fast path** (~10ms): Uses cached authorization handlers in unified mode
        - **Slow path** (~50-100ms): Decrypts key from database using KMS

        ## ⚠️ Security Warning
        **This endpoint currently has NO permission validation**. Any authenticated user can sign any event kind with any content. Permission checks are coming in a future release.

        ## Supported Event Kinds
        Currently accepts all Nostr event kinds (0-65535), including:
        - `kind: 0` - User metadata
        - `kind: 1` - Short text note
        - `kind: 3` - Contact list
        - `kind: 4` - Encrypted direct message
        - `kind: 5` - Deletion
        - `kind: 1984` - Reporting
        - `kind: 9734-9735` - Zaps
        - `kind: 10000+` - Replaceable events
        - `kind: 20000+` - Ephemeral events
        - `kind: 30000+` - Parameterized replaceable events
      tags:
        - Signing
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SignEventRequest'
            examples:
              text_note:
                summary: Sign a text note (kind 1)
                value:
                  event:
                    kind: 1
                    content: "Hello from Keycast!"
                    tags: []
                    created_at: 1234567890
              dm:
                summary: Sign encrypted DM (kind 4)
                value:
                  event:
                    kind: 4
                    content: "encrypted_content_here"
                    tags: [["p", "recipient_pubkey"]]
                    created_at: 1234567890
      responses:
        '200':
          description: Event successfully signed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SignEventResponse'
        '401':
          description: Unauthorized (invalid or missing JWT)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: User not found or key not available
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Signing failed (KMS error, invalid key, etc.)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /ap/keys:
    post:
      summary: Create or return an actor's ActivityPub RSA key
      description: |
        Mints (or returns, idempotently) an RSA-2048 keypair for an actor and returns its
        SPKI public PEM for embedding in `publicKey.publicKeyPem`. The private key is stored
        encrypted-at-rest and is never returned. Calling again returns the existing key
        with `created: false` — the key is never regenerated (federated keys are cached by
        remote servers). Auth: ServiceToken (with `pubkey` or `actor`) or an OAuth UCAN
        for the same actor.
      tags:
        - ActivityPub
      security:
        - ServiceToken: []
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApCreateKeyRequest'
      responses:
        '200':
          description: Key created or already existed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApKeyResponse'
        '400':
          description: Invalid or missing pubkey
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: UCAN pubkey mismatch
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /ap/keys/{actor_or_pubkey}:
    get:
      summary: Get an actor's ActivityPub public key PEM
      description: |
        Returns the actor's public PEM, lazily minting the RSA key if needed. The path
        accepts either a hex Nostr pubkey or a URL-encoded ActivityPub actor URL.
      tags:
        - ActivityPub
      security:
        - ServiceToken: []
        - BearerAuth: []
      parameters:
        - in: path
          name: actor_or_pubkey
          required: true
          schema:
            type: string
          description: Hex Nostr pubkey or URL-encoded ActivityPub actor URL
      responses:
        '200':
          description: Public key PEM
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApPublicKeyResponse'
        '404':
          description: No AP key for this actor
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /ap/sign:
    post:
      summary: Sign an HTTP-Signature signing string (RSA-SHA256)
      description: |
        Signs the exact caller-supplied signing string with RSASSA-PKCS1-v1_5 + SHA-256 and
        returns the base64 signature. The caller builds the draft-cavage signing string and
        assembles the final `Signature:` header. The private key never leaves Keycast.
        Suspended/banned accounts are rejected. Service-token callers identify the actor
        with `pubkey` or `actor`; UCAN callers need a live OAuth authorization for the
        same actor.
      tags:
        - ActivityPub
      security:
        - ServiceToken: []
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApSignRequest'
      responses:
        '200':
          description: Signature
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApSignResponse'
        '403':
          description: Account restricted or pubkey mismatch
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: No AP key for this actor
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /user/bunker:
    get:
      summary: Get NIP-46 bunker URL
      description: |
        Retrieve the NIP-46 bunker connection string for traditional relay-based signing.

        Use this when you need full NIP-46 compatibility with permission validation, or when HTTP signing is not available.
      tags:
        - User
      security:
        - BearerAuth: []
      responses:
        '200':
          description: Bunker URL retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BunkerUrlResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /user/pubkey:
    get:
      summary: Get user's public key
      description: Returns the user's Nostr public key in both hex and npub (bech32) formats.
      tags:
        - User
      security:
        - BearerAuth: []
      responses:
        '200':
          description: Public key retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PubkeyResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /user/profile:
    get:
      summary: Get user profile
      description: Retrieve the authenticated user's profile information including email, username, and Nostr metadata.
      tags:
        - User
      security:
        - BearerAuth: []
      responses:
        '200':
          description: Profile retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserProfile'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    post:
      summary: Update user profile
      description: Update username, display name, or avatar URL for the authenticated user.
      tags:
        - User
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                username:
                  type: string
                  example: "alice"
                display_name:
                  type: string
                  example: "Alice Smith"
                avatar_url:
                  type: string
                  format: uri
                  example: "https://example.com/avatar.jpg"
      responses:
        '200':
          description: Profile updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserProfile'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /user/atproto/enable:
    post:
      summary: Enable ATProto provisioning
      description: Enable ATProto opt-in after username claim, return the claimed username with a pending lifecycle state, and trigger provisioning.
      tags:
        - User
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AtprotoEnableRequest'
      responses:
        '202':
          description: ATProto provisioning accepted and lifecycle set to pending
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AtprotoStatusResponse'
        '400':
          description: Username missing, unclaimed, or mismatched
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /user/atproto/status:
    get:
      summary: Get ATProto lifecycle status
      description: Returns the authenticated user's enabled flag, lifecycle state, DID, last provisioning error, and claimed username.
      tags:
        - User
      security:
        - BearerAuth: []
      responses:
        '200':
          description: Current ATProto status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AtprotoStatusResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: User not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /user/atproto/disable:
    post:
      summary: Disable ATProto publishing
      description: Disable ATProto publishing for the authenticated user, trigger downstream cleanup, and return enabled=false with state=disabled.
      tags:
        - User
      security:
        - BearerAuth: []
      responses:
        '200':
          description: ATProto publishing disabled
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AtprotoStatusResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /account/{pubkey}/crosspost:
    put:
      summary: Toggle Bluesky crossposting
      description: Enable or disable Bluesky publishing for the authenticated user's account.
      tags:
        - User
      security:
        - BearerAuth: []
      parameters:
        - in: path
          name: pubkey
          required: true
          schema:
            type: string
          description: Authenticated user's hex pubkey.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AtprotoCrosspostRequest'
      responses:
        '200':
          description: Updated ATProto publishing status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AtprotoStatusResponse'
        '400':
          description: Username missing or request invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Authenticated user does not own the requested pubkey
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /user/sessions:
    get:
      summary: List active sessions
      description: Get all active NIP-46 authorization sessions for the authenticated user.
      tags:
        - User
      security:
        - BearerAuth: []
      responses:
        '200':
          description: Sessions retrieved
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SessionInfo'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /user/sessions/revoke:
    post:
      summary: Revoke a session
      description: Revoke an active NIP-46 authorization session by its bunker public key.
      tags:
        - User
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                bunker_pubkey:
                  type: string
                  description: Bunker public key to revoke
              required:
                - bunker_pubkey
      responses:
        '200':
          description: Session revoked
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /.well-known/nostr.json:
    get:
      summary: NIP-05 discovery
      description: |
        NIP-05 identifier verification endpoint and nostr-login discovery metadata.

        Query by username: `/.well-known/nostr.json?name=alice`

        Response behavior:
        - With `name` query: returns `names` mapping for lookup
        - Without `name` query: returns `names: {}` and `nip46` discovery data
      tags:
        - Discovery
      parameters:
        - name: name
          in: query
          required: false
          description: Username to look up
          schema:
            type: string
            example: alice
      responses:
        '200':
          description: NIP-05 discovery response
          content:
            application/json:
              schema:
                type: object
                properties:
                  names:
                    type: object
                    additionalProperties:
                      type: string
                    example:
                      alice: "abc123..."
                  nip46:
                    type: object
                    description: Present when `name` query is omitted.
                    properties:
                      relay:
                        type: string
                        description: Relay URL used for NIP-46 communication
                        example: "wss://relay.example.com"
                      nostrconnect_url:
                        type: string
                        description: URL template with `<nostrconnect>` placeholder
                        example: "https://login.divine.video/api/connect/<nostrconnect>"
                    example:
                      relay: "wss://relay.example.com"
                      nostrconnect_url: "https://login.divine.video/api/connect/<nostrconnect>"

  /.well-known/oauth-authorization-server:
    get:
      summary: ATProto authorization server metadata
      description: OAuth metadata for the dedicated ATProto authorization server surface.
      tags:
        - Discovery
      responses:
        '200':
          description: Authorization server metadata
          content:
            application/json:
              schema:
                type: object
                required:
                  - issuer
                  - authorization_endpoint
                  - token_endpoint
                  - pushed_authorization_request_endpoint
                  - scopes_supported
                  - token_endpoint_auth_methods_supported
                  - token_endpoint_auth_signing_alg_values_supported
                  - client_id_metadata_document_supported
                  - authorization_response_iss_parameter_supported
                  - require_pushed_authorization_requests
                  - dpop_signing_alg_values_supported
                properties:
                  issuer:
                    type: string
                    format: uri
                  authorization_endpoint:
                    type: string
                    format: uri
                  token_endpoint:
                    type: string
                    format: uri
                  pushed_authorization_request_endpoint:
                    type: string
                    format: uri
                  scopes_supported:
                    type: array
                    items:
                      type: string
                  token_endpoint_auth_methods_supported:
                    type: array
                    items:
                      type: string
                  token_endpoint_auth_signing_alg_values_supported:
                    type: array
                    items:
                      type: string
                  client_id_metadata_document_supported:
                    type: boolean
                  authorization_response_iss_parameter_supported:
                    type: boolean
                  require_pushed_authorization_requests:
                    type: boolean
                  dpop_signing_alg_values_supported:
                    type: array
                    items:
                      type: string

  /atproto/oauth/par:
    post:
      summary: Create an ATProto pushed authorization request
      description: Requires an initial DPoP proof and returns a session `request_uri` plus a `DPoP-Nonce` header for the next token exchange. Confidential clients with `token_endpoint_auth_method=private_key_jwt` must also include `client_assertion_type` and `client_assertion`.
      tags:
        - Authentication
      parameters:
        - in: header
          name: DPoP
          required: true
          schema:
            type: string
          description: Compact DPoP proof JWT for the PAR request.
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
                - client_id
                - redirect_uri
                - scope
                - code_challenge
                - code_challenge_method
              properties:
                client_id:
                  type: string
                  format: uri
                  description: Public clients may use a direct origin-style client ID. Confidential clients use an HTTPS metadata-document URL.
                redirect_uri:
                  type: string
                  format: uri
                scope:
                  type: string
                  example: atproto
                state:
                  type: string
                code_challenge:
                  type: string
                code_challenge_method:
                  type: string
                  example: S256
                client_assertion_type:
                  type: string
                  example: urn:ietf:params:oauth:client-assertion-type:jwt-bearer
                  description: Required when the resolved client metadata declares `token_endpoint_auth_method=private_key_jwt`.
                client_assertion:
                  type: string
                  description: ES256 `private_key_jwt` assertion whose `iss` and `sub` equal `client_id` and whose `aud` equals the authorization-server issuer.
      responses:
        '200':
          description: PAR created
          headers:
            DPoP-Nonce:
              schema:
                type: string
              description: Nonce that must be echoed in the next DPoP proof sent to the token endpoint.
          content:
            application/json:
              schema:
                type: object
                required:
                  - request_uri
                  - expires_in
                properties:
                  request_uri:
                    type: string
                  expires_in:
                    type: integer
        '400':
          description: Invalid PAR request or missing/invalid DPoP proof
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

  /atproto/oauth/token:
    post:
      summary: Exchange an ATProto authorization code or refresh token
      description: Requires a DPoP proof, rotates the session nonce via `DPoP-Nonce`, and returns DPoP-bound access and refresh tokens. Confidential clients must continue to present the same `private_key_jwt` client-auth key that was bound at PAR.
      tags:
        - Authentication
      parameters:
        - in: header
          name: DPoP
          required: true
          schema:
            type: string
          description: Compact DPoP proof JWT for the token request.
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              oneOf:
                - type: object
                  required:
                    - grant_type
                    - code
                    - client_id
                    - redirect_uri
                    - code_verifier
                  properties:
                    grant_type:
                      type: string
                      enum: [authorization_code]
                    code:
                      type: string
                    client_id:
                      type: string
                    redirect_uri:
                      type: string
                    code_verifier:
                      type: string
                    client_assertion_type:
                      type: string
                      example: urn:ietf:params:oauth:client-assertion-type:jwt-bearer
                    client_assertion:
                      type: string
                - type: object
                  required:
                    - grant_type
                    - refresh_token
                    - client_id
                  properties:
                    grant_type:
                      type: string
                      enum: [refresh_token]
                    refresh_token:
                      type: string
                    client_id:
                      type: string
                    client_assertion_type:
                      type: string
                      example: urn:ietf:params:oauth:client-assertion-type:jwt-bearer
                    client_assertion:
                      type: string
      responses:
        '200':
          description: DPoP-bound token response
          headers:
            DPoP-Nonce:
              schema:
                type: string
              description: Rotated nonce for the next DPoP-bound request in the session.
          content:
            application/json:
              schema:
                type: object
                required:
                  - access_token
                  - token_type
                  - expires_in
                  - refresh_token
                  - scope
                  - sub
                properties:
                  access_token:
                    type: string
                  token_type:
                    type: string
                    example: DPoP
                  expires_in:
                    type: integer
                  refresh_token:
                    type: string
                  scope:
                    type: string
                    example: atproto
                  sub:
                    type: string
        '400':
          description: Invalid grant or DPoP proof. A PKCE `code_verifier` that does not match the stored `code_challenge` returns the RFC 6749 error code `invalid_grant` with an `error_description`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'

tags:
  - name: Authentication
    description: User registration and authentication endpoints
  - name: Signing
    description: Fast HTTP signing for Nostr events
  - name: User
    description: User profile and session management
  - name: Discovery
    description: NIP-05 identifier discovery
  - name: ActivityPub
    description: RSA key custody and HTTP-Signature signing for the ActivityPub gateway