Skip to main content

​
Overview

The CDP SDK provides low-level authentication utilities for generating JWT tokens and authentication headers. These are primarily used internally by the SDK, but can be useful for advanced use cases like custom HTTP clients or WebSocket connections.

​
HTTP Authentication

​
getAuthHeaders

Generates authentication headers for CDP API requests.
​
options
GetAuthHeadersOptions
required
​
headers
Record<string, string>
Object containing authentication headers:
  • Authorization: Bearer token
  • Content-Type: application/json
  • X-Wallet-Auth: Wallet auth token (if applicable)
  • Correlation-Context: SDK correlation data
import { getAuthHeaders } from "@coinbase/cdp-sdk";

const headers = await getAuthHeaders({
  apiKeyId: "your-api-key-id",
  apiKeySecret: "your-api-key-secret",
  requestMethod: "POST",
  requestHost: "api.cdp.coinbase.com",
  requestPath: "/platform/v1/accounts",
  walletSecret: "your-wallet-secret",
  requestBody: {
    name: "My Account",
  },
});

// Use with fetch or other HTTP clients
const response = await fetch("https://api.cdp.coinbase.com/platform/v1/accounts", {
  method: "POST",
  headers,
  body: JSON.stringify({ name: "My Account" }),
});

​
getCorrelationData

Generates correlation data for request tracking.
​
source
string
The source identifier.
​
sourceVersion
string
The source version.
​
correlationData
string
Encoded correlation data string.
import { getCorrelationData } from "@coinbase/cdp-sdk";

const correlationData = getCorrelationData("my-app", "1.0.0");
// Returns: "sdk_version=X.X.X,sdk_language=typescript,source=my-app,source_version=1.0.0"

​
JWT Generation

​
generateJwt

Generates a JWT token for authenticating with CDP REST APIs. Supports both EC (ES256) and Ed25519 (EdDSA) keys.
​
options
JwtOptions
required
​
jwt
string
The generated JWT token.
import { generateJwt } from "@coinbase/cdp-sdk";

// For REST API requests
const jwt = await generateJwt({
  apiKeyId: "your-api-key-id",
  apiKeySecret: "your-api-key-secret",
  requestMethod: "GET",
  requestHost: "api.cdp.coinbase.com",
  requestPath: "/platform/v1/accounts",
});

// For WebSocket connections (all request params null)
const wsJwt = await generateJwt({
  apiKeyId: "your-api-key-id",
  apiKeySecret: "your-api-key-secret",
  requestMethod: null,
  requestHost: null,
  requestPath: null,
});

​
generateWalletJwt

Generates a wallet authentication JWT for endpoints requiring wallet auth.
​
options
WalletJwtOptions
required
​
jwt
string
The generated wallet auth JWT.
import { generateWalletJwt } from "@coinbase/cdp-sdk";

const walletJwt = await generateWalletJwt({
  walletSecret: "your-wallet-secret",
  requestMethod: "POST",
  requestHost: "api.cdp.coinbase.com",
  requestPath: "/platform/v1/accounts",
  requestData: {
    name: "My Account",
  },
});

​
WebSocket Authentication

​
getWebSocketAuthHeaders

Generates authentication headers for WebSocket connections.
​
options
GetWebSocketAuthHeadersOptions
required
​
headers
Record<string, string>
Object containing WebSocket authentication headers.
import { getWebSocketAuthHeaders } from "@coinbase/cdp-sdk";

const headers = await getWebSocketAuthHeaders({
  apiKeyId: "your-api-key-id",
  apiKeySecret: "your-api-key-secret",
});

// Use with WebSocket clients
const ws = new WebSocket("wss://api.cdp.coinbase.com/ws", {
  headers,
});

​
Axios Integration

​
withAuth

Axios interceptor for automatic authentication. 
import axios from "axios";
import { axiosHooks } from "@coinbase/cdp-sdk";

const client = axios.create({
  baseURL: "https://api.cdp.coinbase.com",
});

// Apply auth interceptor
axiosHooks.withAuth(client, {
  apiKeyId: "your-api-key-id",
  apiKeySecret: "your-api-key-secret",
  walletSecret: "your-wallet-secret",
});

// All requests now include auth headers automatically
const response = await client.post("/platform/v1/accounts", {
  name: "My Account",
});

​
Key Format Support

​
EC Keys (ES256)

PEM format EC private keys: 
-----BEGIN EC PRIVATE KEY-----
MHcCAQEEIHJc7...
-----END EC PRIVATE KEY-----

​
Ed25519 Keys (EdDSA)

Base64 encoded 64-byte keys (32 bytes seed + 32 bytes public key): 
xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx==

​
Error Handling

import { 
  UndefinedWalletSecretError, 
  InvalidWalletSecretFormatError,
  UserInputValidationError 
} from "@coinbase/cdp-sdk";

try {
  const headers = await getAuthHeaders({
    apiKeyId: "your-api-key-id",
    apiKeySecret: "invalid-key",
    requestMethod: "GET",
    requestHost: "api.cdp.coinbase.com",
    requestPath: "/platform/v1/accounts",
  });
} catch (error) {
  if (error instanceof UserInputValidationError) {
    console.error("Invalid key format:", error.message);
  } else if (error instanceof UndefinedWalletSecretError) {
    console.error("Wallet secret required for this endpoint");
  } else if (error instanceof InvalidWalletSecretFormatError) {
    console.error("Invalid wallet secret format:", error.message);
  }
}

​
When to Use These Utilities

These low-level utilities are useful when:
  1. Building custom HTTP clients
  2. Implementing WebSocket connections
  3. Creating middleware or proxies
  4. Debugging authentication issues
  5. Integrating with non-standard frameworks
For most use cases, you should use the CdpClient which handles authentication automatically.

Build docs developers (and LLMs) love

Get started for freeTalk to us