WhiteBIT OAuth API Keys API

openapi: 3.2.0
info:
  title: OAuth 2.0 API Reference OAuth API Keys API
  description: WhiteBIT OAuth 2.0 API for authentication and account management
  version: 1.0.0
servers:
- url: https://whitebit.com
  description: WhiteBIT Global Server
- url: https://whitebit.eu
  description: WhiteBIT EU Server
tags:
- name: OAuth API Keys
  description: Partner-facing endpoints for managing API keys created via the OAuth API key flow.
paths:
  /oauth2/api-key/info:
    get:
      summary: Check OAuth API key existence
      description: 'The endpoint returns whether a partner-issued API key already exists for the authenticated user and OAuth2 client pair. The endpoint is Bearer-authenticated, so it is reachable only once the partner holds a token for that user: a returning partner calls it before redirecting the user again, while a first-time authorization reaches it only after the authorization code has been exchanged. When a key already exists, skip the redirect and surface the appropriate message to the user.


        The endpoint reports absence through the payload, never through an error status. A key that was deleted, a key belonging to a different OAuth2 client, and a manually created key are all reported as `exists: false` with an empty `permissions` list. The only failure status is `401`, which covers every problem with the token itself.


        **Required scope:** `apikeys.read`.


        **Region availability:** The endpoint is available on the global server (`https://whitebit.com`) only.'
      tags:
      - OAuth API Keys
      security:
      - BearerAuth: []
      servers:
      - url: https://whitebit.com
        description: WhiteBIT Global Server
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      exists:
                        type: boolean
                        description: A partner-issued API key exists for the authenticated user and OAuth2 client pair. `false` covers every absence case — no key was ever created, the key was deleted by the user or by the system, the key belongs to a different OAuth2 client, or the key was created manually rather than through OAuth.
                        example: true
                      isEnabled:
                        type: boolean
                        description: The existing key is active. `false` when no key exists or when a key exists but is disabled (post-inactivity, awaiting user deletion from the dashboard).
                        example: true
                      externalId:
                        type:
                        - string
                        - 'null'
                        format: uuid
                        description: External UUID of the existing key. `null` when `exists` is `false`.
                        example: 550e8400-e29b-41d4-a716-446655440000
                      permissions:
                        type: array
                        description: Permission groups assigned to the key. Empty array when `exists` is `false`, and also when the user granted zero permissions during the OAuth handshake — the key is still created in that case, and the user deletes it and re-runs the flow to grant a usable set. For a disabled key (`isEnabled` is `false`), the array still reflects the permissions the user granted at creation time, so the partner can show the original scope.
                        items:
                          type: object
                          properties:
                            name:
                              type: string
                              description: Locale-independent identifier of the permission group. Use the value for partner-side logic.
                              example: trading
                            title:
                              type: string
                              description: Translated label of the permission group. The value depends on the authenticated user's locale — display only, never branch on the value.
                              example: Trading
                            urls:
                              type: array
                              description: Endpoint permissions inside the group. `enable` set to `true` means the user granted the action during the OAuth handshake; `enable` set to `false` means the action was offered but not granted.
                              items:
                                type: object
                                properties:
                                  url:
                                    type: string
                                    description: Endpoint path the permission controls.
                                    example: /v2/order
                                  enable:
                                    type: boolean
                                    description: The user granted the action during the OAuth handshake.
                                    example: true
        '401':
          description: Missing, invalid, or expired Bearer token. A token that does not carry the `apikeys.read` scope returns the same status — an insufficient scope is not reported separately.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      message:
                        type: array
                        items:
                          type: string
                        example:
                        - Unauthorized.
      operationId: getOauth2ApiKeyInfo
      x-operation-id-source: derived
  /oauth2/api-key/{externalId}/secret:
    get:
      summary: Retrieve OAuth API key secret
      description: 'The endpoint retrieves the API secret for a partner-issued API key. The endpoint returns the secret exactly once per key — a subsequent call returns `409 Conflict`.


        **Required scope:** `apikeys.read`.


        **Region availability:** The endpoint is available on the global server (`https://whitebit.com`) only.


        Store the API secret in encrypted backend storage on first retrieval. The secret is not recoverable after this call returns.'
      tags:
      - OAuth API Keys
      security:
      - BearerAuth: []
      servers:
      - url: https://whitebit.com
        description: WhiteBIT Global Server
      parameters:
      - name: externalId
        in: path
        required: true
        description: External UUID of the API key. Obtain the value from `GET /oauth2/api-key/info`.
        schema:
          type: string
          format: uuid
          example: 550e8400-e29b-41d4-a716-446655440000
      responses:
        '200':
          description: Successful response. The secret is returned exactly once.
          headers:
            Cache-Control:
              description: Always `no-store` to prevent the secret from being cached.
              schema:
                type: string
                example: no-store
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      apiSecret:
                        type: string
                        description: The API secret. Persist immediately in encrypted backend storage — the secret is not recoverable.
                        example: YOUR_API_SECRET
        '401':
          description: Missing or invalid Bearer token, or token does not carry the `apikeys.read` scope.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      message:
                        type: array
                        items:
                          type: string
                        example:
                        - Unauthorized.
        '403':
          description: The key does not belong to the authenticated OAuth2 client, or the key is not a partner-issued key.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      message:
                        type: array
                        items:
                          type: string
                        example:
                        - Forbidden.
        '404':
          description: Key not found.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      message:
                        type: array
                        items:
                          type: string
                        example:
                        - Key not found.
        '409':
          description: The secret has already been retrieved for this key. Recovery requires deleting the key and restarting the OAuth API key flow.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      message:
                        type: array
                        items:
                          type: string
                        example:
                        - Secret already retrieved.
        '423':
          description: A concurrent secret-retrieval attempt holds the lock. Retry after a short delay.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      message:
                        type: array
                        items:
                          type: string
                        example:
                        - Temporary lock, retry shortly.
      operationId: getOauth2ApiKeyByExternalIdSecret
      x-operation-id-source: derived
  /oauth2/api-key/{externalId}:
    delete:
      summary: Delete OAuth API key
      description: 'The endpoint deletes a partner-issued API key owned by the authenticated OAuth2 client. The deletion triggers an email notification to the user. The endpoint applies to active keys — disabled keys must be removed by the user from the WhiteBIT dashboard.


        **Required scope:** `apikeys.delete`.


        **Region availability:** The endpoint is available on the global server (`https://whitebit.com`) only.'
      tags:
      - OAuth API Keys
      security:
      - BearerAuth: []
      servers:
      - url: https://whitebit.com
        description: WhiteBIT Global Server
      parameters:
      - name: externalId
        in: path
        required: true
        description: External UUID of the API key.
        schema:
          type: string
          format: uuid
          example: 550e8400-e29b-41d4-a716-446655440000
      responses:
        '200':
          description: Successful deletion.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items: {}
                    example: []
        '401':
          description: Missing or invalid Bearer token, or token does not carry the `apikeys.delete` scope.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      message:
                        type: array
                        items:
                          type: string
                        example:
                        - Unauthorized.
        '403':
          description: The key does not belong to the authenticated OAuth2 client.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      message:
                        type: array
                        items:
                          type: string
                        example:
                        - Forbidden.
        '404':
          description: Key not found.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      message:
                        type: array
                        items:
                          type: string
                        example:
                        - Key not found.
      operationId: deleteOauth2ApiKeyByExternalId
      x-operation-id-source: derived
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 'OAuth 2.0 Bearer Token authentication. Include the access token in the Authorization header.


        Example: `Authorization: Bearer YOUR_ACCESS_TOKEN`

        '