Skip to main content

​
Authentication

The CDP SDK uses a secure authentication system based on API keys, wallet secrets, and JWT (JSON Web Token) authentication. This guide explains how authentication works and how to configure it properly.

​
Overview

CDP uses two types of credentials for authentication:
  1. CDP API Keys - Used to authenticate all API requests
  2. Wallet Secret - Required for operations that create, modify, or delete accounts and send transactions

Authentication Flow

  1. SDK generates a JWT token using your API key
  2. JWT is signed with ES256 (EC) or EdDSA (Ed25519) algorithm
  3. Token is sent with each API request in the Authorization header
  4. For write operations, an additional Wallet Auth JWT is generated

​
Creating API Keys

1

Access the CDP Portal

Navigate to the CDP Portal and sign in to your account.
2

Create a new API Key

Click “Create API Key” and follow the prompts. You’ll receive:
  • API Key ID - A UUID identifier for your key
  • API Key Secret - The private key (either EC or Ed25519 format)
3

Create a Wallet Secret

In the same portal, create a Wallet Secret for signing transactions. This is a separate credential used for write operations.
4

Store credentials securely

Save these credentials in a secure location. You’ll need them to initialize the SDK.
Never commit API keys or wallet secrets to version control!

​
Configuration Methods

There are multiple ways to configure authentication in CDP SDK: The simplest and most secure method for most applications: 
CDP_API_KEY_ID=your-api-key-id
CDP_API_KEY_SECRET=your-api-key-secret
CDP_WALLET_SECRET=your-wallet-secret
Then initialize the client without passing credentials: 
import { CdpClient } from "@coinbase/cdp-sdk";
import dotenv from "dotenv";

dotenv.config();

const cdp = new CdpClient();
// Credentials are automatically loaded from environment

​
Method 2: Direct Configuration

Pass credentials directly to the client constructor: 
import { CdpClient } from "@coinbase/cdp-sdk";

const cdp = new CdpClient({
  apiKeyId: "your-api-key-id",
  apiKeySecret: "your-api-key-secret",
  walletSecret: "your-wallet-secret",
});
Hardcoding credentials is not recommended for production applications. Use environment variables or secret management services instead.

​
JWT Token Generation

The SDK automatically generates JWT tokens for authentication. Here’s how it works under the hood:

​
API Key JWT

For standard API requests, the SDK generates a JWT with these claims: 
{
  "sub": "your-api-key-id",
  "iss": "cdp",
  "uris": ["POST api.cdp.coinbase.com/platform/v1/accounts"],
  "nbf": 1234567890,
  "exp": 1234567890,
  "iat": 1234567890
}

​
Wallet Auth JWT

For write operations (creating accounts, sending transactions), an additional Wallet Auth JWT is generated: 
{
  "uris": ["POST api.cdp.coinbase.com/platform/v1/accounts"],
  "reqHash": "sha256-hash-of-request-body",
  "iat": 1234567890,
  "nbf": 1234567890,
  "jti": "unique-nonce"
}
The SDK handles all JWT generation automatically. You don’t need to manage tokens manually.

​
Key Formats

CDP supports two types of private key formats:

​
EC Keys (ES256)

Elliptic Curve keys in PEM format: 
-----BEGIN EC PRIVATE KEY-----
MHcCAQEEIKL...(base64)...==
-----END EC PRIVATE KEY-----

​
Ed25519 Keys (EdDSA)

Edwards curve keys in base64 format: 
xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx==
The SDK automatically detects which format you’re using and applies the correct signing algorithm.

​
Authentication Code Examples

Here’s how JWT authentication is implemented in the SDK: 
import { SignJWT, importPKCS8 } from "jose";

async function generateJwt(options: JwtOptions): Promise<string> {
  const now = Math.floor(Date.now() / 1000);
  const expiresIn = options.expiresIn || 120;

  const claims = {
    sub: options.apiKeyId,
    iss: "cdp",
    uris: [`${options.requestMethod} ${options.requestHost}${options.requestPath}`],
  };

  const ecKey = await importPKCS8(options.apiKeySecret, "ES256");

  return await new SignJWT(claims)
    .setProtectedHeader({ alg: "ES256", kid: options.apiKeyId, typ: "JWT" })
    .setIssuedAt(now)
    .setNotBefore(now)
    .setExpirationTime(now + expiresIn)
    .sign(ecKey);
}

​
Read vs Write Operations

​
Read Operations

Read-only operations (like listing accounts or checking balances) only require the API Key JWT: 
// Only API key needed
const accounts = await cdp.evm.listAccounts();

​
Write Operations

Write operations require both API Key and Wallet Secret: 
// Requires API key + wallet secret
const account = await cdp.evm.createAccount();
If you try to perform a write operation without a wallet secret, you’ll receive an authentication error.

​
Security Best Practices

Never Expose Keys

Never commit API keys or secrets to version control or expose them in client-side code

Use Environment Variables

Store credentials in environment variables or secure secret management services

Rotate Keys Regularly

Regularly rotate your API keys and wallet secrets

Limit Key Permissions

Use separate keys for different environments (dev, staging, production)

​
Production Secret Management

For production environments, use dedicated secret management:
  • AWS Secrets Manager - For AWS-based deployments
  • Google Cloud Secret Manager - For GCP deployments
  • Azure Key Vault - For Azure deployments
  • HashiCorp Vault - For multi-cloud or on-premises
  • Doppler - For centralized secret management

​
Troubleshooting

​
Missing API Keys Error

If you see this error: 
Missing required CDP Secret API Key configuration parameters.
Make sure you have:
  1. Set the environment variables CDP_API_KEY_ID and CDP_API_KEY_SECRET
  2. Or passed them directly to the CdpClient constructor

​
Invalid Key Format Error

If you see: 
Invalid key format - must be either PEM EC key or base64 Ed25519 key
Check that your API key secret is in the correct format (PEM for EC keys, base64 for Ed25519).

​
Wallet Secret Required Error

If you see: 
Wallet Secret is not defined
You’re attempting a write operation without setting CDP_WALLET_SECRET. Set it in your environment or pass it to the constructor.

​
Next Steps

Quickstart

Start building with authenticated API calls

API Reference

Explore all available API endpoints

Build docs developers (and LLMs) love

Get started for freeTalk to us