Coinbase Commerce Authentication API

openapi: 3.2.0
info:
  description: Coinbase Retail Advanced Trade API for derivatives trading.
  title: Coinbase Retail Advanced Trade (Deribit) Authentication API
  version: 2.1.1
servers:
- url: https://drb.coinbase.com/api/v2
tags:
- name: Authentication
paths:
  /private/logout:
    get:
      description: 'Gracefully terminate the current WebSocket connection and optionally invalidate all tokens associated with the session.


        This method provides a clean way to close WebSocket connections while preserving active orders when **Cancel On Disconnect (COD)** is enabled.


        **Use Cases:**


        - **Clean Shutdown:** Properly close WebSocket connections during application shutdown or restart

        - **Order Preservation:** Close connections without triggering order cancellations when COD is enabled

        - **Session Management:** Invalidate tokens to ensure security when closing connections

        - **Maintenance Operations:** Temporarily disconnect for system maintenance without affecting trading positions


        **Cancel On Disconnect (COD) Behavior:**


        When Cancel On Disconnect is enabled for your connection, this method provides a safe way to close the connection without triggering automatic order cancellations. This is different from other disconnection scenarios:


        - **Graceful logout** (this method): Orders are **NOT cancelled**, even if COD is enabled

        - **Unexpected disconnection:** Orders are **cancelled** if COD is enabled

        - **Inactivity timeout:** Orders are **cancelled** if COD is enabled

        - **Heartbeat failure:** Orders are **cancelled** if COD is enabled


        This distinction allows you to perform planned disconnections (e.g., for maintenance, updates, or reconnection) while preserving your active orders.


        **WebSocket Only:**


        This method is designed exclusively for WebSocket connections. Attempting to use it via REST/HTTP will result in a 400 error response.


        **Note:** This method has no response. The WebSocket connection is closed immediately after the request is processed.


        Try in API console'
      parameters:
      - name: invalidate_token
        in: query
        description: '<b>Token Invalidation:</b> By default, all tokens created during the current session are invalidated when you call this method. You can control this behavior using this parameter: <ul><li><b>invalidate_token=true</b> (default): All session tokens are invalidated, requiring re-authentication for new connections</li><li><b>invalidate_token=false</b>: Tokens remain valid, allowing you to reconnect using the same authentication</li></ul>'
        required: false
        schema:
          type: boolean
      requestBody:
        description: JSON-RPC request body
        content:
          application/json:
            examples:
              request:
                description: JSON-RPC Request Example
                value:
                  id: 42
                  jsonrpc: '2.0'
                  method: private/logout
                  params:
                    access_token: 1529453804065.h2QrBgvn.oS36pCOmuK9EX7954lzCSkUioEtTMg7F5ShToM0ZfYlqU05OquXkQIe2_DDEkPhzmoPp1fBp0ycXShR_0jf-SMSXEdVqxLRWuOw-_StG5BMjToiAl27CbHY4P92MPhlMblTOtTImE81-5dFdyDVydpBwmlfKM3OSQ39kulP9bbfw-2jhyegOL0AgqJTY_tj554oHCQFTbq0A0ZWukukmxL2yu6iy34XdzaJB26Igy-3UxGBMwFu53EhjKBweh7xyP2nDm57-wybndJMtSyTGDXH3vjBVclo1iup5yRP
                    invalidate_token: true
      responses:
        '200':
          description: Connection closed
      security:
      - ApiKey: []
      - OAuth2: []
      tags:
      - Authentication
      x-mint:
        href: /api-reference/authentication/private-logout
        metadata:
          keywords:
          - private/logout
          - invalidate_token
          og:title: private/logout
          title: private/logout
      summary: Get private logout
      x-summary-source: derived
      operationId: getPrivateLogout
      x-operation-id-source: derived
  /public/auth:
    post:
      description: 'Authenticate using a Coinbase-issued credential.


        **Only `POST` is supported.** Send the JSON-RPC request in the request body; query-string credentials are not accepted.'
      requestBody:
        description: JSON-RPC request body
        required: true
        content:
          application/json:
            examples:
              request:
                description: JSON-RPC Request Example
                value:
                  id: 1
                  jsonrpc: '2.0'
                  method: public/auth
                  params:
                    grant_type: coinbase_cdp
                    token: '...'
            schema:
              type: object
              properties:
                id:
                  description: The id that was sent in the request
                  type: integer
                  example: 1
                jsonrpc:
                  description: The JSON-RPC version (2.0)
                  type: string
                  enum:
                  - '2.0'
                method:
                  description: The method name
                  type: string
                  enum:
                  - public/auth
                params:
                  type: object
                  properties:
                    grant_type:
                      description: Coinbase grant type used to authenticate.
                      type: string
                      example: coinbase_cdp
                      enum:
                      - coinbase_cdp
                      - coinbase_oauth2
                    token:
                      description: Coinbase-issued credential matching `grant_type`.
                      type: string
                      example: '...'
                  required:
                  - grant_type
                  - token
              required:
              - jsonrpc
              - id
              - method
              - params
      responses:
        '200':
          $ref: '#/components/responses/PublicAuthResponse'
      security: []
      tags:
      - Authentication
      x-mint:
        metadata:
          keywords:
          - public/auth
          - grant_type
          - token
          og:title: public/auth
          title: public/auth
      summary: Create public auth
      x-summary-source: derived
      operationId: postPublicAuth
      x-operation-id-source: derived
components:
  schemas:
    api_key_features:
      description: 'List of enabled advanced on-key features.<br><br><b>Available options:</b><br>- <code>restricted_block_trades</code>: Limit the block_trade read the scope of the API key to block trades that have been made using this specific API key<br>- <code>block_trade_approval</code>: Block trades created using this API key require additional user approval. Methods that use <code>block_rfq</code> scope are not affected by Block Trade approval feature'
      type: array
      items:
        type: string
    PublicAuthResponse:
      type: object
      properties:
        id:
          description: The id that was sent in the request
          type: integer
        jsonrpc:
          description: The JSON-RPC version (2.0)
          type: string
          enum:
          - '2.0'
        result:
          type: object
          properties:
            access_token:
              description: Access token to be used for authentication of subsequent requests.
              type: string
              example: 843SehgeX5n6XxEU4XbABx4Cny5Akai5iHiJePTsvUw7
            enabled_features:
              $ref: '#/components/schemas/api_key_features'
            expires_in:
              description: Token lifetime in seconds
              type: integer
              example: 315360000
            google_login:
              description: The access token was acquired by logging in through Google.
              type: boolean
            mandatory_tfa_status:
              description: 2FA is required for privileged methods
              type: string
              example: enabled
            refresh_token:
              description: Can be used to request a new token (with a new lifetime)
              type: string
              example: 6faf8L36JdaSqsjCEEiwqifPpj6JB18RWwiWHrsGTZ91
            scope:
              description: Space-separated list of granted scopes
              type: string
            sid:
              description: Optional Session id
              type: string
            state:
              description: Copied from the input (if applicable)
              type: string
            token_type:
              description: Authorization type, always `bearer`
              type: string
              enum:
              - bearer
          required:
          - access_token
          - token_type
          - expires_in
          - scope
      required:
      - result
      - jsonrpc
  responses:
    PublicAuthResponse:
      description: Success response
      content:
        application/json:
          examples:
            response:
              description: Response example
              value:
                id: 9929
                jsonrpc: '2.0'
                result:
                  access_token: a3f8c2e1d4b7f09e5c6a2d8b1e4f7c0a9d3b6e2f5a8c1d4e7b0f3a6c9d2e5f8
                  enabled_features: []
                  expires_in: 3600
                  refresh_token: 1582628593469.1GP4rQd0.A9Wa78o5kFRIUP49mScaD1CqHgiK50HOl2VA6kCtWa8BQZU5Dr03BhcbXPNvEh3I_MVixKZXnyoBeKJwLl8LXnfo180ckAiPj3zOclcUu4zkXuF3NNP3sTPcDf1B3C1CwMKkJ1NOcf1yPmRbsrd7hbgQ-hLa40tfx6Oa-85ymm_3Z65LZcnCeLrqlj_A9jM
                  scope: wallet:user:read wallet:accounts:read wallet:transactions:read wallet:buys:create
                  token_type: bearer
          schema:
            $ref: '#/components/schemas/PublicAuthResponse'
  securitySchemes:
    ApiKey:
      description: 'Call `public/auth` with `grant_type: coinbase_cdp` and a CDP JWT. Send the returned `access_token` as `Authorization: Bearer`.'
      scheme: bearer
      type: http
    OAuth2:
      description: 'Call `public/auth` with `grant_type: coinbase_oauth2` and an OAuth access token. Send the returned `access_token` as `Authorization: Bearer`.'
      flows:
        authorizationCode:
          authorizationUrl: https://login.coinbase.com/oauth2/auth
          scopes:
            wallet:accounts:read: View your accounts.
            wallet:accounts:update: Authorize `wallet:accounts:update` operations.
            wallet:buys:create: Place, edit, and cancel orders.
            wallet:payment-methods:read: View your payment methods.
            wallet:trades:create: Convert cryptocurrencies.
            wallet:trades:read: View your cryptocurrency conversions.
            wallet:transactions:read: View your transactions.
            wallet:transactions:transfer: Transfer funds between accounts.
            wallet:user:read: View your account information.
            wallet:user:update: Update your account information.
          tokenUrl: https://login.coinbase.com/oauth2/token
      type: oauth2
x-provenance:
  method: harvested
  publisher: Coinbase Commerce
  source: https://docs.cdp.coinbase.com/api-reference/coinbase-deribit-app-api/adv-starbase-openapi.json
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)