CDP API Keys

Use API keys to authenticate requests to the suite of APIs offered on CDP.

Key Types

Type	Usage	Configuration
Secret API Key	Server-side: Used to securely authenticate server-to-server communication and must be kept private for maximum security.	- Custom scopes - IP allowlist
Client API Key	Client-side: Used to identify applications from client-side code (ie, OnchainKit) and used in the RPC endpoint.	- Key rotation with expiration - Domain allowlist
OAuth Client User Authentication	Client-side: Used to authenticate end users and access their Coinbase accounts with their permission.	- Configurable scopes - Redirect URIs - Access & refresh tokens

Secret API Keys

New API Key Signing Algorithm: Transitioning to Ed25519 We’re excited to announce a performance and usability upgrade to our API key signing algorithm! Previously, API keys were signed using ECDSA, but going forward, all new API keys will be signed with Ed25519. Learn more about this decision.

Creating Secret API Keys

1. Navigate to the Coinbase Developer Platform and select Secret API Keys under the API Keys tab
2. Click the Create API key button.
3. Enter an API key nickname and click Create & Download.
4. Secure your private/public key pair in a safe location.

To regenerate an API key, click Manage to delete and recreate the key.

IP Allowlist (Optional)

Restrict the use of your Secret API key to specific IPs (IPv4 and IPv6 supported). Separate each IP with a comma (example: “192.168.45.123, 10.54.213.87” or “2001:db8:1234:5678::1, 2001:db8:abcd:9876::42”).

Client API Key

Rotating the Client API Key

1. Navigate to the Coinbase Developer Platform and select Client API Key under the API Keys tab
2. Click the Rotate button.
3. Select an expiration time for your previous key. This is to ensure you can replace your previous key without any downtime.
4. Click confirm and replace all references to your previous key, including in your RPC endpoint.

Domain Allowlist

Restrict the use of your Client API key to specific domains by validating the Origin header in API requests. This prevents unauthorized websites from using your key.

Important Considerations:

• If domains are allowlisted, any API request without an Origin header will be rejected.
• Allowlisting a parent domain (e.g., example.com) does not automatically include its subdomains (e.g., sub.example.com).
• Wildcards are not supported; each domain must be explicitly specified.

OAuth Clients

Creating OAuth Clients

1. Navigate to the Coinbase Developer Platform and select OAuth under the API Keys tab
2. Click the Create client button
3. Enter your application details:
   • Application name (shown during OAuth)
   • Application type
   • Service offerings
   • Redirect URIs
4. Configure any advanced options if needed
5. Store your client ID and client secret securely

Authorization Flow

// Authorization Request
const authUrl = `https://login.coinbase.com/oauth2/auth?
  response_type=code
  &client_id=${YOUR_CLIENT_ID}
  &redirect_uri=${YOUR_REDIRECT_URL}
  &state=${SECURE_RANDOM}
  &scope=wallet:accounts:read`;

Exchange Code for Tokens:

// Token Exchange
POST https://login.coinbase.com/oauth2/token
{
  "grant_type": "authorization_code",
  "code": "TEMPORARY_CODE",
  "client_id": "YOUR_CLIENT_ID",
  "client_secret": "YOUR_CLIENT_SECRET",
  "redirect_uri": "YOUR_REDIRECT_URI"
}

Token Management

• Access tokens expire after 1 hour
• Refresh tokens can only be used once
• Use refresh tokens to obtain new access tokens when needed

Available Scopes

The following scopes control what your application can access:

• wallet:accounts:read: View account balances
• wallet:user:read: Access user information
• wallet:transactions:read: View transaction history
• wallet:transactions:send: Send cryptocurrency (requires 2FA)
• offline_access: Get refresh tokens

Secret API Key Best Practices

When using secret API keys in the Coinbase Developer Portal, it is crucial that you take the necessary steps to securely protect them. Publicly exposing your credentials could result in your account being compromised and / or a loss of funds.

Here are some best practices you can follow to keep your CDP API keys secure.

1. Never embed keys directly in code

Embedding secret API keys in code increases the risk of accidentally exposing your keys to the public. For example, if you need to share your code, you may forget to remove the keys in your code. Instead, store your keys in environment variables or in files outside of your application source tree.

2. Never store keys inside your application’s source tree

If you’re storing secret API keys in files, keep the files outside your application source tree to ensure your keys don’t end up in your source code control system (e.g., GitHub).

3. Restrict keys to sources that need them

Restricting your secret API keys to only the sources that need them, reduces impact of a compromised API Key. With the allowlist feature, you can specify IPs or CIDRs that ensure API requests signed with your keys are only honored from the origins (or IPs) that you define.

Steps:

1. Navigate to Secret API keys.
2. Navigate to the API key you’d like to edit and click Manage.
3. Click Edit Key and expand API restrictions.
4. Add an IP or CIDR under IP allowlist and save the changes.

4. Restrict signatures to certain APIs

If you have multiple APIs enabled in your project, you should restrict usage of certain signatures (JWT tokens) to specific APIs to minimize the risk of replay attacks. You can do so by attaching the API request path as part of the signing body so that the signature can only be used for that specific API.

5. Delete unnecessary keys

If you no longer need any secret API keys, make sure to delete them to minimize your exposure to attack.

Steps

1. Navigate to Secret API keys.
2. Navigate to the API key you’d like to edit and click Manage.
3. Click Delete Key.
4. Copy and paste the the ID associated with the key and click Delete Key to confirm.

6. Rotate keys periodically

Rotating your secret API keys reduces the risks associated with the same key being compromised. Coinbase Developer Platform uses asymmetric cryptography meaning that you will need to create new keys and delete the old keys to get the rotation done.

Ed25519 Signature Algorithm

From February 2025 onwards, new CDP API keys will default to using the Ed25519 signature algorithm for enhanced security and performance. Existing API keys signed with ECDSA will continue to function without interruption, but you will need to update your SDK library to support the new key type.

Secret Format Comparison

🔑 [Previously] ECDSA - PEM Format

-----BEGIN EC PRIVATE KEY-----
MHcCAQEEIGzF05P0YzdmqnlP7ZTExK3tTldWkRbJXp8B/5G+zBKoAoGCCqGSM49
AwEHoUQDQgAEXFh8azfrBkMqBVAiLbLbbZYwK9L/9WNBOfcDYgM1GoyWy3qA5Yc
94yD0gKnKTTOY5z5Y6m8sghG2SnUTPA9Lg==
-----END EC PRIVATE KEY-----

🔐 [Now] Ed25519 - Base64 Format

88WPC/9+fV8a7/PGLh+MOL26PBni9KEqP/u3Tl0tWCw=

Benefits

• Faster Verification: Ed25519 offers better performance, especially in high-load environments.
• Stronger Security: Provides resistance against common cryptographic attacks.
• Simpler Key Management: Smaller keys and deterministic signatures improve usability.

Transitioning Away from ECDSA We will continue to support all existing ECDSA keys, and for a limited time you will still be able to generate new ECDSA keys in “Advanced Settings”. However, we strongly recommend upgrading to Ed25519 as soon as possible to take advantage of its improved security and performance.

ECSDA vs. Ed25519

What is ECDSA?

ECDSA (Elliptic Curve Digital Signature Algorithm) is a widely used asymmetric cryptographic algorithm based on elliptic curve cryptography (ECC). It’s commonly used in secure communications, blockchain, and digital signatures.

What is Ed25519?

Ed25519 is a modern public-key signature algorithm based on the Edwards-curve Digital Signature Algorithm (EdDSA), specifically using the Curve25519 elliptic curve. It is designed to be fast, simple, and resistant to common cryptographic vulnerabilities.

ECDSA vs. Ed25519 Key Differences

Feature	ECDSA	Ed25519
Algorithm Type	Elliptic Curve DSA	Edwards-curve DSA
Curve	secp256r1, secp256k1, etc.	Curve25519
Key Size	256-bit (secp256r1)	256-bit
Signature Size	Variable (~64-72 bytes)	64 bytes
Deterministic Signatures	❌ Requires random nonce	✅ Always deterministic
Performance	Slower verification	Faster signing & verification
Security	Strong but depends on nonce randomness	More resistant to implementation flaws
Private Key Shape	32-byte scalar (can be DER-encoded in PEM format)	32-byte seed (often stored with a 64-byte expanded form)