Bridge API Keys API

openapi: 3.0.2
info:
  title: Bridge API Keys API
  description: APIs to move into, out of, and between any form of a dollar
  version: '1'
servers:
- url: https://api.bridge.xyz/v0
  description: The base path for all resources
security:
- ApiKey: []
tags:
- name: API Keys
paths:
  /api_keys:
    post:
      summary: Create a scoped API key
      description: 'Create a new API key restricted to a subset of scopes. The returned `value` is the only

        opportunity to retrieve the plaintext secret — store it securely. This endpoint does not

        accept an `Idempotency-Key` header; each call creates a new key.


        Callers may only grant scopes they themselves hold (scope subsetting). Unrestricted keys

        may create scoped keys; scoped keys need the `api_key:create` scope. Up to 500 scoped

        keys may exist per developer.

        '
      tags:
      - API Keys
      requestBody:
        description: The scopes to grant the new API key. Must be a non-empty array drawn from `ApiKeyScope`.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateApiKeyInput'
            examples:
              ScopedKey:
                $ref: '#/components/examples/CreateApiKeyRequest'
      responses:
        '201':
          description: The API key was created. `value` is returned exactly once.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiKeyWithSecret'
              examples:
                SuccessfulCreateApiKeyResponse:
                  $ref: '#/components/examples/SuccessfulCreateApiKeyResponse'
        '401':
          $ref: '#/components/responses/AuthenticationError'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '500':
          $ref: '#/components/responses/UnexpectedError'
  /api_keys/whoami:
    get:
      summary: Describe the calling API key
      description: Return metadata about the API key authenticating this request, including its scopes. The plaintext secret is never returned.
      tags:
      - API Keys
      responses:
        '200':
          description: Metadata describing the calling API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiKey'
              examples:
                SuccessfulWhoAmIResponse:
                  $ref: '#/components/examples/SuccessfulWhoAmIResponse'
        '401':
          $ref: '#/components/responses/AuthenticationError'
        '500':
          $ref: '#/components/responses/UnexpectedError'
components:
  responses:
    AuthenticationError:
      description: Missing or invalid API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            MissingTokenError:
              summary: No Api-Key header
              description: The header may be missing or misspelled.
              value:
                code: required
                location: header
                name: Api-Key
                message: Missing Api-Key header
            InvalidTokenError:
              summary: Invalid key in Api-Key header
              value:
                code: invalid
                location: header
                name: Api-Key
                message: Invalid Api-Key header
    UnexpectedError:
      description: Unexpected error. User may try and send the request again.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            UnexpectedError:
              summary: An unexpected error
              value:
                errors:
                - code: unexpected
                  message: An expected error occurred, you may try again later
    BadRequestError:
      description: Request containing missing or invalid parameters.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            BadCustomerRequestErrorExample:
              summary: Bad customer request
              value:
                code: bad_customer_request
                message: fields missing from customer body.
                name: first_name,ssn
  examples:
    SuccessfulCreateApiKeyResponse:
      summary: A successful create request for a scoped API key.
      value:
        id: 5f1f5b3a-8c2b-4e5f-9d88-e0b2a7d3a1e8
        type: Private
        owner_type: Developer
        owner_id: e802b3a4-f453-4da8-8a5b-dd50cede1e4f
        prefix: sk-live
        last_4: 9f2c
        state: Active
        created_at: '2026-04-22T15:04:05Z'
        updated_at: '2026-04-22T15:04:05Z'
        name: Customer service key
        scopes:
        - customer:read
        - customer:create
        value: sk-live-0123456789abcdef0123456789ab9f2c
    SuccessfulWhoAmIResponse:
      summary: A successful whoami request for a scoped API key.
      value:
        id: 5f1f5b3a-8c2b-4e5f-9d88-e0b2a7d3a1e8
        type: Private
        owner_type: Developer
        owner_id: e802b3a4-f453-4da8-8a5b-dd50cede1e4f
        prefix: sk-live
        last_4: 9f2c
        state: Active
        created_at: '2026-04-22T15:04:05Z'
        updated_at: '2026-04-22T15:04:05Z'
        name: Customer service key
        scopes:
        - customer:read
        - customer:create
    CreateApiKeyRequest:
      summary: Create a scoped API key limited to reading and creating customers.
      value:
        name: Customer service key
        scopes:
        - customer:read
        - customer:create
  schemas:
    Error:
      required:
      - code
      - message
      properties:
        code:
          type: string
          minLength: 1
          maxLength: 256
        message:
          type: string
          minLength: 1
          maxLength: 512
        source:
          title: ErrorSource
          required:
          - location
          - key
          properties:
            location:
              type: string
              enum:
              - path
              - query
              - body
              - header
            key:
              type: string
              description: Comma separated names of the properties or parameters causing the error
    ApiKeyScope:
      description: A scope that may be granted to a scoped API key. Unrestricted keys are created via the Dashboard and implicitly hold the standard scopes; they cannot be requested here.
      type: string
      enum:
      - api_key:create
      - api_key:self:read
      - audit_log:read
      - batch_settlement:create
      - batch_settlement:read
      - card:create
      - card:delete
      - card:read
      - card:update
      - crypto_return_policy:create
      - crypto_return_policy:delete
      - crypto_return_policy:read
      - crypto_return_policy:update
      - customer:create
      - customer:delete
      - customer:read
      - customer:update
      - customer_creation_request:create
      - customer_creation_request:read
      - developer_fee:create
      - developer_fee:read
      - developer_fee:update
      - developer_trade_configuration:read
      - developer_trade_configuration:update
      - exchange_rate:read
      - external_account:create
      - external_account:delete
      - external_account:read
      - external_account:update
      - inquiry:read
      - inquiry:resume
      - liquidation_address:create
      - liquidation_address:drain:read
      - liquidation_address:drain:update
      - liquidation_address:read
      - liquidation_address:update
      - prefunded_account:create
      - prefunded_account:history:read
      - prefunded_account:read
      - rewards:read
      - sandbox:simulate
      - spender_contract:approval:create
      - spender_contract:approval:read
      - spender_contract:create
      - spender_contract:read
      - tos_link:create
      - tos_link:read
      - transfer:create
      - transfer:create:privy_custodial_wallet
      - transfer:delete
      - transfer:read
      - transfer:update
      - virtual_account:create
      - virtual_account:delete
      - virtual_account:history:read
      - virtual_account:read
      - virtual_account:transaction:read
      - virtual_account:update
      - wallet:create
      - wallet:create:privy_custodial_wallet
      - wallet:customer:read
      - wallet:delete
      - wallet:developer:read
      - wallet:update
      - webhook:create
      - webhook:delete
      - webhook:read
      - webhook:update
    CreateApiKeyInput:
      required:
      - scopes
      properties:
        scopes:
          description: Scopes to grant the new key. Must be a non-empty array. Each scope must be one you yourself hold (scope subsetting).
          type: array
          minItems: 1
          items:
            $ref: '#/components/schemas/ApiKeyScope'
        name:
          description: A human-readable label for this key, up to 100 characters. Useful for identifying the key's purpose later.
          type: string
          maxLength: 100
    ApiKeyWithSecret:
      description: Returned only on key creation. `value` is the plaintext secret and is shown exactly once.
      allOf:
      - $ref: '#/components/schemas/ApiKey'
      - required:
        - value
        properties:
          value:
            description: The plaintext secret for this API key. Store it securely — it cannot be retrieved again.
            type: string
            example: sk-live-0123456789abcdef0123456789ab9f2c
    ApiKey:
      required:
      - id
      - type
      - owner_type
      - owner_id
      - prefix
      - last_4
      - state
      - created_at
      - updated_at
      - scopes
      properties:
        id:
          description: The unique identifier for this API key.
          type: string
          format: uuid
        type:
          description: Whether the key was created programmatically (Private) or via the Dashboard (Public).
          type: string
          enum:
          - Public
          - Private
        owner_type:
          description: The type of entity that owns the key. Always `Developer`.
          type: string
          enum:
          - Developer
        owner_id:
          description: The developer ID that owns the key.
          type: string
          format: uuid
        prefix:
          description: The environment prefix of the key. `sk-live` in production, `sk-test` in sandbox.
          type: string
          enum:
          - sk-live
          - sk-test
        last_4:
          description: The last four characters of the key, shown alongside the prefix for disambiguation in audit logs.
          type: string
        state:
          description: Lifecycle state of the key.
          type: string
          enum:
          - Active
          - Deleted
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        scopes:
          description: 'The scopes authorized on this key. A single-element list containing `bridge:api_unrestricted`

            denotes an unrestricted key (all standard scopes). Any other list denotes a scoped key.

            '
          type: array
          items:
            type: string
        name:
          description: The human-readable label for this key, if one was provided at creation.
          type: string
          maxLength: 100
  securitySchemes:
    ApiKey:
      type: apiKey
      name: Api-Key
      in: header