Creating new API key on Deribit – DRB API testing

You can create new Deribit API key using front-end interface or by Deribit API. If you want to use the API, please head to the Creating the API key using the API section.

Notice

Please note your first API key has to be created using front-end interface.

Front-end interface

Please head to the API section inside top right Account Panel.

Press ‘Add new key’ on the right side of the interface.

Select between Deribit-generated key and Self-generated key. Please refer to Asymmetric API keys for more details on Self-generated keys.

Declare scopes and other API key details:

Scopes: Describes maximal access for authorization with given key. For more information about access scopes, refer to the section Scopes and Access Control below and consult official API documentation
Name field: This is a custom input you can enter to use as an identifier for the key.
Features field: Additional optional features related to this API key. They may be expanded in future releases.
1. Restricted Block Trades feature
  
  Restricted block trades feature limits the block_trade:read scope of the API key to block trades that have been made using this specific API key. This method can be employed to restrict the visibility of user private block trades with third parties to whom the user has provided their API key.
2. Block Trade Approval Feature
  
  Block trade approval introduces an additional layer to the block trade verification process. When activated, it necessitates an additional approval from the user from a different API key before a block trade can be executed with the specified API key. This functionality provides users with enhanced oversight, particularly when a registered partner possessing an API key intends to carry out a block trade on their behalf.
IP Whitelisting: An additional security feature, this field restricts which IPs can connect using this API key.

Once created you will receive Client ID and Client Secret

Client ID:The Client ID is a public identifier of the API key. It's not a secret. It can be exposed in web browsers, source code, or wherever else without immediate security concerns. It's mainly used to identify the key and is not used on its own for authentication.

Client Secret: The Client Secret is a confidential piece of information. Think of it as a password. It should be kept secret and never exposed to the public. Exposing the Client Secret can lead to serious security risks. It's used, in combination with the Client ID, to authenticate.

Scopes and Access Control

Each API key on Deribit is assigned a default access scope, which defines the maximum permissions that can be granted when authenticating. These scopes determine what operations can be performed using the authenticated session.

When calling the public/auth endpoint, you can request one or more access scopes by including them in the scope parameter, separated by spaces:

scope: account:none custody:read block_trade:read

Important rules about scopes:

You cannot exceed the API key’s default scope. The server will cap the token’s permissions to the key’s maximum. For example, if a key’s default scope is account:read and you request account:read_write, the issued token will still only have account:read access .
The effective scope is an intersection of the key’s default scope and the requested scope. In practice, this means the token’s actual permissions = (key’s max permissions) ∩ (requested permissions). Any scope not permitted by the key will be dropped, and any scope you don’t request defaults to the key’s setting. The token’s granted scope is returned in the scope field of the auth response, so you can verify what you got .
If you omit the scope parameter entirely, Deribit will default to a connection-level token with read-only access for trading and wallet (i.e. no write permissions) – essentially the lowest privileges your key allows. It’s recommended to explicitly specify a scope even if it’s just connection or a session name, to avoid ambiguity.
The assigned scope for the token is returned in the scope field of the public/auth response.

When creating API keys, you should follow the principle of least privilege. Grant only the scopes necessary for the use-case. For example, if you are making a data dashboard or monitoring tool that doesn’t need to trade, create an API key with only read scopes (e.g. account:read trade:read wallet:read, etc.) . Avoid any ...:write scopes on such a key, so that even if the key is compromised it cannot place orders or withdraw funds . You can also enable IP whitelisting on the key to restrict its usage to your server’s IP – an extra safety measure.

Creating the API key using the API

To create an API key via the Deribit API, use the private/create_api_key endpoint. Please note that this is a private endpoint and requires prior authentication through the public/auth method.

Request

{
  "method": "private/create_api_key",
  "params": {
    "name": "test_key",
    "max_scope": "account:read trade:read_write wallet:read"
  },
  "jsonrpc": "2.0",
  "id": 1
}

Response

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "max_scope": "trade:read_write wallet:read account:read",
    "ip_whitelist": [],
    "client_secret": "5gE6eyXwolP4RcVmsNqq8rhjtnjv5M1_HNHUHKAXsgt",
    "client_id": "GgUXjYUj",
    "enabled_features": [],
    "timestamp": 1721816749587,
    "name": "test_key",
    "id": 11,
    "enabled": true,
    "default": false
  }
}

Managing keys: You can use private/edit_api_key or private/remove_api_key (with proper scopes) to manage keys. Each key’s Client ID and Secret can be viewed via API (private/list_api_keys) only if your token scope allows it .

Creating read-only access for non‑trading stuff

For use cases like internal dashboards, monitoring tools, or finance reporting—where trading actions are not required—you can create a secure read-only API key. This setup ensures that the key can only retrieve data without being able to execute any orders or initiate withdrawals, which significantly reduces risk in case the key is ever exposed.

When configuring your new API key, make sure to only assign read-only scopes. These typically include:

block_rfq:read – view RFQs
block_trade:read – view existing block trades and trade history
account:read – access account details
wallet:read – check balances and transaction history
trade:read – review past trades and open positions
custody:read – used by third-party custodians when enabled by the client

Avoid selecting any scopes that end with write. This ensures that the key cannot be used to place orders, transfer funds, or perform any actions that could impact your portfolio.

You may also consider enabling IP whitelisting to further restrict the usage of the key to trusted systems. This is particularly helpful for automation scripts or monitoring dashboards operating from static server locations.

This approach follows the principle of least privilege and is strongly recommended when API keys are used for integrations that do not require active trading functionality.

Authentication

You can authenticate using your API credentials in two ways:

Directly in the Deribit login web-page using “Log In with API credentials” option
Using Deribit API by calling the public/auth method and passing your client_id, client_secret, and the desired read-only scopes

Make sure that the scopes requested in the auth call match the permissions assigned to the key.

For step-by-step guidance on authentication, visit Logging in to your Deribit Account

Testing out your new API key

You can test your new API key in the Deribit API console. Simply click the link to be redirected to the console, where you will already be authenticated with your new API key.