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 with the authenticated user's key, without a NIP-46 round trip.

        ## Which authorization applies
        - **OAuth access tokens** name the authorization they were issued for. That
          authorization must belong to the token's user, be in this tenant, and be
          neither revoked nor expired. Otherwise the request gets `403`.
        - **Tokens that name no authorization** (login sessions) use the newest active
          authorization for the token's origin. If there is none, the request gets `403`.

        ## Policy
        The event is checked against the policy of that authorization before signing.
        An authorization without a policy may sign any event kind. An event the policy
        does not allow gets `401`.

        Accounts flagged as verified minors have restrictions on signing
        direct-message kinds (4, 13, 14, 15 and 1059). A refused request gets `403`.

        ## Performance
        - **Cached signer** (~10ms): used when a signer for the token's authorization
          is already loaded
        - **Otherwise** (~50-100ms): decrypts the user's key from the database
      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: Missing or invalid token, or the authorization's policy does not allow this event
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: |
            The token's authorization cannot be used (it belongs to another user or
            tenant, or is revoked, expired, or unknown), there is no active
            authorization for the token's origin, or the verified-minor direct-message
            rules refuse the event
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: No signing key stored for this user
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: Temporary failure loading or using the key, or `event` could not be parsed as an unsigned event
          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'
        '403':
          description: Token is an OAuth access token issued to a client that is not first-party
          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'
        '403':
          description: Token is an OAuth access token issued to a client that is not first-party
          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