Deribit Authentication API

openapi: 3.2.0
info:
  title: Deribit Authentication API
  version: 2.1.1
servers:
- url: https://test.deribit.com/api/v2
tags:
- name: Authentication
paths:
  /public/auth:
    get:
      tags:
      - Authentication
      parameters:
      - name: grant_type
        in: query
        schema:
          type: string
          enum:
          - client_credentials
          - client_signature
          - refresh_token
          example: client_credentials
        required: true
        description: Method of authentication
      - name: client_id
        in: query
        schema:
          type: string
          example: fo7WAPRm4P
        required: true
        description: Required for grant type `` `client_credentials` `` and `` `client_signature` ``
      - name: client_secret
        in: query
        schema:
          type: string
          example: W0H6FJW4IRPZ1MOQ8FP6KMC5RZDUUKXS
        required: true
        description: Required for grant type `` `client_credentials` ``
      - name: refresh_token
        in: query
        schema:
          type: string
        required: true
        description: Required for grant type `` `refresh_token` ``
      - name: timestamp
        in: query
        schema:
          type: integer
        required: true
        description: 'Required for grant type `` `client_signature` ``.


          Provides time when request has been generated (milliseconds since the UNIX epoch).

          '
      - name: signature
        in: query
        schema:
          type: string
        required: true
        description: 'Required for grant type `` `client_signature` ``.


          It''s a cryptographic signature calculated over provided fields using user **secret key**. The signature should be calculated as an HMAC (Hash-based Message Authentication Code) with `` `SHA256` `` hash algorithm.

          '
      - name: nonce
        in: query
        schema:
          type: string
        description: 'Optional for grant type `` `client_signature` ``.


          Delivers user generated initialization vector for the server token.

          '
        required: false
      - name: data
        in: query
        schema:
          type: string
        description: 'Optional for grant type `` `client_signature` ``.


          Contains any user specific value.

          '
        required: false
      - name: state
        in: query
        schema:
          type: string
        description: Will be passed back in the response.
        required: false
      - name: scope
        in: query
        schema:
          type: string
          example: connection
        description: 'Describes type of the access for assigned token.



          **Possible values:**


          - `` `connection` ``

          - `` `session:name` ``

          - `` `trade:[read, read_write, none]` ``

          - `` `wallet:[read, read_write, none]` ``

          - `` `account:[read, read_write, none]` ``

          - `` `expires:NUMBER` ``

          - `` `ip:ADDR` ``



          Details are elucidated in [Access scope](https://docs.deribit.com/articles/access-scope)

          '
        required: false
      responses:
        '200':
          $ref: '#/components/responses/PublicAuthResponse'
      requestBody:
        content:
          application/json:
            examples:
              request:
                value:
                  jsonrpc: '2.0'
                  id: 9929
                  method: public/auth
                  params:
                    grant_type: client_credentials
                    client_id: fo7WAPRm4P
                    client_secret: W0H6FJW4IRPZ1MOQ8FP6KMC5RZDUUKXS
                description: JSON-RPC Request Example
        description: JSON-RPC request body
      description: 'Retrieve an OAuth access token, to be used for authentication of ''private'' requests.


        **📖 Related Article:** Authentication


        **Authentication Methods:**


        Three methods of authentication are supported:


        - ``client_credentials`` - Using the client id and client secret that can be found on the API page on the website. This is the simplest method, suitable for server-to-server applications and quick setup.


        - ``client_signature`` - Enhanced security method that uses a cryptographic signature instead of sending the client secret directly. You generate an HMAC-SHA256 signature of a string containing a timestamp, a random nonce, and optional data, using your Client Secret as the key. This method requires `` `client_id` ``, `` `timestamp` `` (current time in milliseconds), `` `nonce` ``, `` `signature` ``, and optionally a `` `data` `` field. Deribit verifies the signature instead of requiring the raw secret. Best for enhanced security, asymmetric key pairs, and avoiding secret transmission. See the Client Signature (WebSocket) guide for detailed signature calculation instructions.


        - ``refresh_token`` - Using a refresh token that was received from an earlier invocation. This allows you to obtain a new access token without re-supplying your Client ID and Client Secret. Best for long-lived sessions, token renewal, and avoiding re-authentication.


        **Response:**


        The response will contain an access token, expiration period (number of seconds that the token is valid) and a refresh token that can be used to get a new set of tokens.


        Try in API console'
      x-mint:
        metadata:
          title: public/auth
          og:title: public/auth
          keywords:
          - public/auth
          - grant_type
          - client_id
          - client_secret
          - refresh_token
          - timestamp
          - signature
          - nonce
          - data
          - state
          - scope
          - access_token
          - token_type
          - expires_in
          - sid
          - enabled_features
          - mandatory_tfa_status
          - google_login
        href: /api-reference/authentication/public-auth
      summary: Get public auth
      x-summary-source: derived
      operationId: getPublicAuth
      x-operation-id-source: derived
  /public/exchange_token:
    get:
      tags:
      - Authentication
      parameters:
      - name: refresh_token
        in: query
        schema:
          type: string
          example: 1568800656974.1CWcuzUS.MGy49NK4hpTwvR1OYWfpqMEkH4T4oDg4tNIcrM7KdeyxXRcSFqiGzA_D4Cn7mqWocHmlS89FFmUYcmaN2H7lNKKTnhRg5EtrzsFCCiuyN0Wv9y-LbGLV3-Ojv_kbD50FoScQ8BDXS5b_w6Ir1MqEdQ3qFZ3MLcvlPiIgG2BqyJX3ybYnVpIlrVrrdYD1-lkjLcjxOBNJvvUKNUAzkQ
        required: true
        description: Refresh token
      - name: subject_id
        in: query
        schema:
          type: integer
          example: 10
        required: true
        description: New subject id
      - name: scope
        in: query
        schema:
          type: string
        required: false
        description: Optional scope override for the new session. Cannot exceed caller's permissions. Supports `session` scope for direct session creation during token exchange.
      responses:
        '200':
          $ref: '#/components/responses/PublicTokenResponse'
      requestBody:
        content:
          application/json:
            examples:
              request:
                value:
                  jsonrpc: '2.0'
                  id: 7619
                  method: public/exchange_token
                  params:
                    refresh_token: 1568800656974.1CWcuzUS.MGy49NK4hpTwvR1OYWfpqMEkH4T4oDg4tNIcrM7KdeyxXRcSFqiGzA_D4Cn7mqWocHmlS89FFmUYcmaN2H7lNKKTnhRg5EtrzsFCCiuyN0Wv9y-LbGLV3-Ojv_kbD50FoScQ8BDXS5b_w6Ir1MqEdQ3qFZ3MLcvlPiIgG2BqyJX3ybYnVpIlrVrrdYD1-lkjLcjxOBNJvvUKNUAzkQ
                    subject_id: 10
                description: JSON-RPC Request Example
        description: JSON-RPC request body
      description: 'Generates a token for a new subject id. This method can be used to switch between subaccounts.


        **📖 Related Articles:**

        - Fork and Exchange Tokens

        - Managing Subaccounts


        Try in API console'
      x-mint:
        metadata:
          title: public/exchange_token
          og:title: public/exchange_token
          keywords:
          - public/exchange_token
          - refresh_token
          - subject_id
          - scope
          - access_token
          - token_type
          - expires_in
          - sid
        href: /api-reference/authentication/public-exchange_token
      summary: Get public exchange token
      x-summary-source: derived
      operationId: getPublicExchangeToken
      x-operation-id-source: derived
  /public/fork_token:
    get:
      tags:
      - Authentication
      parameters:
      - name: refresh_token
        in: query
        schema:
          type: string
          example: 1568800656974.1CWcuzUS.MGy49NK4hpTwvR1OYWfpqMEkH4T4oDg4tNIcrM7KdeyxXRcSFqiGzA_D4Cn7mqWocHmlS89FFmUYcmaN2H7lNKKTnhRg5EtrzsFCCiuyN0Wv9y-LbGLV3-Ojv_kbD50FoScQ8BDXS5b_w6Ir1MqEdQ3qFZ3MLcvlPiIgG2BqyJX3ybYnVpIlrVrrdYD1-lkjLcjxOBNJvvUKNUAzkQ
        required: true
        description: Refresh token
      - name: session_name
        in: query
        schema:
          type: string
          example: forked_session_name
        required: true
        description: New session name
      responses:
        '200':
          $ref: '#/components/responses/PublicTokenResponse'
      requestBody:
        content:
          application/json:
            examples:
              request:
                value:
                  jsonrpc: '2.0'
                  id: 7620
                  method: public/fork_token
                  params:
                    refresh_token: 1568800656974.1CWcuzUS.MGy49NK4hpTwvR1OYWfpqMEkH4T4oDg4tNIcrM7KdeyxXRcSFqiGzA_D4Cn7mqWocHmlS89FFmUYcmaN2H7lNKKTnhRg5EtrzsFCCiuyN0Wv9y-LbGLV3-Ojv_kbD50FoScQ8BDXS5b_w6Ir1MqEdQ3qFZ3MLcvlPiIgG2BqyJX3ybYnVpIlrVrrdYD1-lkjLcjxOBNJvvUKNUAzkQ
                    session_name: forked_session_name
                description: JSON-RPC Request Example
        description: JSON-RPC request body
      description: 'Generates a token for a new named session. This method can be used only with session scoped tokens.


        **📖 More Details:** Fork and Exchange Tokens


        Try in API console'
      x-mint:
        metadata:
          title: public/fork_token
          og:title: public/fork_token
          keywords:
          - public/fork_token
          - refresh_token
          - session_name
          - access_token
          - token_type
          - expires_in
          - scope
          - sid
        href: /api-reference/authentication/public-fork_token
      summary: Get public fork token
      x-summary-source: derived
      operationId: getPublicForkToken
      x-operation-id-source: derived
  /private/logout:
    get:
      tags:
      - Authentication
      parameters:
      - name: invalidate_token
        in: query
        required: false
        schema:
          type: boolean
        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>'
      responses:
        '200':
          description: Connection closed
      requestBody:
        content:
          application/json:
            examples:
              request:
                value:
                  jsonrpc: '2.0'
                  id: 42
                  method: private/logout
                  params:
                    access_token: 1529453804065.h2QrBgvn.oS36pCOmuK9EX7954lzCSkUioEtTMg7F5ShToM0ZfYlqU05OquXkQIe2_DDEkPhzmoPp1fBp0ycXShR_0jf-SMSXEdVqxLRWuOw-_StG5BMjToiAl27CbHY4P92MPhlMblTOtTImE81-5dFdyDVydpBwmlfKM3OSQ39kulP9bbfw-2jhyegOL0AgqJTY_tj554oHCQFTbq0A0ZWukukmxL2yu6iy34XdzaJB26Igy-3UxGBMwFu53EhjKBweh7xyP2nDm57-wybndJMtSyTGDXH3vjBVclo1iup5yRP
                    invalidate_token: true
                description: JSON-RPC Request Example
        description: JSON-RPC request body
      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'
      x-mint:
        metadata:
          title: private/logout
          og:title: private/logout
          keywords:
          - private/logout
          - invalidate_token
        href: /api-reference/authentication/private-logout
      summary: Get private logout
      x-summary-source: derived
      operationId: getPrivateLogout
      x-operation-id-source: derived
components:
  schemas:
    api_key_features:
      items:
        type: string
      type: array
      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'
    PublicTokenResponse:
      properties:
        jsonrpc:
          type: string
          enum:
          - '2.0'
          description: The JSON-RPC version (2.0)
        id:
          type: integer
          description: The id that was sent in the request
        result:
          type: object
          properties:
            access_token:
              type: string
              example: 843SehgeX5n6XxEU4XbABx4Cny5Akai5iHiJePTsvUw7
            token_type:
              type: string
              enum:
              - bearer
              description: Authorization type, allowed value - `bearer`
            expires_in:
              type: integer
              example: 315360000
              description: Token lifetime in seconds
            refresh_token:
              type: string
              example: 6faf8L36JdaSqsjCEEiwqifPpj6JB18RWwiWHrsGTZ91
              description: Can be used to request a new token (with a new lifetime)
            scope:
              type: string
              description: Type of the access for assigned token
            sid:
              type: string
              description: Optional Session id
          required:
          - access_token
          - token_type
          - expires_in
          - refresh_token
          - scope
      required:
      - jsonrpc
      - result
      type: object
    PublicAuthResponse:
      properties:
        jsonrpc:
          type: string
          enum:
          - '2.0'
          description: The JSON-RPC version (2.0)
        id:
          type: integer
          description: The id that was sent in the request
        result:
          type: object
          properties:
            access_token:
              type: string
              example: 843SehgeX5n6XxEU4XbABx4Cny5Akai5iHiJePTsvUw7
              description: OAuth access token to be used for authentication of 'private' requests
            token_type:
              type: string
              enum:
              - bearer
              description: Authorization type, allowed value - `bearer`
            expires_in:
              type: integer
              example: 315360000
              description: Token lifetime in seconds
            refresh_token:
              type: string
              example: 6faf8L36JdaSqsjCEEiwqifPpj6JB18RWwiWHrsGTZ91
              description: Can be used to request a new token (with a new lifetime)
            scope:
              type: string
              description: Type of the access for assigned token
            state:
              type: string
              description: Copied from the input (if applicable)
            sid:
              type: string
              description: Optional Session id
            enabled_features:
              $ref: '#/components/schemas/api_key_features'
            mandatory_tfa_status:
              type: string
              example: enabled
              description: 2FA is required for privileged methods
            google_login:
              type: boolean
              description: The access token was acquired by logging in through Google.
          required:
          - access_token
          - token_type
          - expires_in
          - refresh_token
          - scope
      required:
      - jsonrpc
      - result
      type: object
  responses:
    PublicTokenResponse:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PublicTokenResponse'
          examples:
            response:
              value:
                jsonrpc: '2.0'
                id: 9929
                result:
                  access_token: 1582628593469.1MbQ-J_4.CBP-OqOwm_FBdMYj4cRK2dMXyHPfBtXGpzLxhWg31nHu3H_Q60FpE5_vqUBEQGSiMrIGzw3nC37NMb9d1tpBNqBOM_Ql9pXOmgtV9Yj3Pq1c6BqC6dU6eTxHMFO67x8GpJxqw_QcKP5IepwGBD-gfKSHfAv9AEnLJkNu3JkMJBdLToY1lrBnuedF3dU_uARm
                  expires_in: 31536000
                  refresh_token: 1582628593469.1GP4rQd0.A9Wa78o5kFRIUP49mScaD1CqHgiK50HOl2VA6kCtWa8BQZU5Dr03BhcbXPNvEh3I_MVixKZXnyoBeKJwLl8LXnfo180ckAiPj3zOclcUu4zkXuF3NNP3sTPcDf1B3C1CwMKkJ1NOcf1yPmRbsrd7hbgQ-hLa40tfx6Oa-85ymm_3Z65LZcnCeLrqlj_A9jM
                  scope: session:named_session mainaccount
                  token_type: bearer
              description: Response example
      description: Success response
    PublicAuthResponse:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PublicAuthResponse'
          examples:
            response:
              value:
                jsonrpc: '2.0'
                id: 9929
                result:
                  access_token: 1582628593469.1MbQ-J_4.CBP-OqOwm_FBdMYj4cRK2dMXyHPfBtXGpzLxhWg31nHu3H_Q60FpE5_vqUBEQGSiMrIGzw3nC37NMb9d1tpBNqBOM_Ql9pXOmgtV9Yj3Pq1c6BqC6dU6eTxHMFO67x8GpJxqw_QcKP5IepwGBD-gfKSHfAv9AEnLJkNu3JkMJBdLToY1lrBnuedF3dU_uARm
                  expires_in: 31536000
                  refresh_token: 1582628593469.1GP4rQd0.A9Wa78o5kFRIUP49mScaD1CqHgiK50HOl2VA6kCtWa8BQZU5Dr03BhcbXPNvEh3I_MVixKZXnyoBeKJwLl8LXnfo180ckAiPj3zOclcUu4zkXuF3NNP3sTPcDf1B3C1CwMKkJ1NOcf1yPmRbsrd7hbgQ-hLa40tfx6Oa-85ymm_3Z65LZcnCeLrqlj_A9jM
                  scope: connection mainaccount
                  enabled_features: []
                  token_type: bearer
              description: Response example
      description: Success response