Skip to main content

​
Authentication Overview

The CDP SDK Python library provides authentication utilities for generating JWT tokens and managing authenticated HTTP requests. These utilities support both EC (ES256) and Ed25519 (EdDSA) keys.

​
JWT Generation

​
generate_jwt

def generate_jwt(options: JwtOptions) -> str:
Generate a JWT (Bearer token) for authenticating with Coinbase’s APIs. Supports both EC (ES256) and Ed25519 (EdDSA) keys.
​
options
JwtOptions
required
The configuration options for generating the JWT.
​
return
str
The generated JWT (Bearer token) string.
​
raises
ValueError
If required parameters are missing, invalid, or if JWT signing fails.

​
JwtOptions

Configuration options for JWT generation.
​
api_key_id
str
required
The API key ID. Examples:
  • 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'
  • 'organizations/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/apiKeys/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx'
​
api_key_secret
str
required
The API key secret. Examples:
  • 'xxxxxx...xx==' (Edwards key Ed25519)
  • '-----BEGIN EC PRIVATE KEY-----\n...\n-----END EC PRIVATE KEY-----\n' (EC key ES256)
​
request_method
str | None
The HTTP method for the request (e.g. ‘GET’, ‘POST’), or None for JWTs intended for websocket connections.
​
request_host
str | None
The host for the request (e.g. ‘api.cdp.coinbase.com’), or None for JWTs intended for websocket connections.
​
request_path
str | None
The path for the request (e.g. ‘/platform/v1/wallets’), or None for JWTs intended for websocket connections.
​
expires_in
int | None
default:"120"
Optional expiration time in seconds (defaults to 120).
​
audience
list[str] | None
Optional audience claim for the JWT.
# Example: Generate JWT for REST API request
from cdp.auth import generate_jwt, JwtOptions

jwt_token = generate_jwt(
    JwtOptions(
        api_key_id="your-api-key-id",
        api_key_secret="your-api-key-secret",
        request_method="GET",
        request_host="api.cdp.coinbase.com",
        request_path="/platform/v1/accounts",
        expires_in=120,
    )
)

​
generate_wallet_jwt

def generate_wallet_jwt(options: WalletJwtOptions) -> str:
Build a wallet authentication JWT for the given API endpoint URL. Used for authenticating with specific endpoints that require wallet authentication.
​
options
WalletJwtOptions
required
The configuration options for generating the wallet auth JWT.
​
return
str
The generated JWT (Bearer token) string.
​
raises
ValueError
If required parameters are missing or if JWT signing fails.

​
WalletJwtOptions

Configuration options for Wallet Auth JWT generation.
​
wallet_auth_key
str
required
The wallet authentication key.
​
request_method
str
required
The HTTP method for the request (e.g. ‘GET’, ‘POST’).
​
request_host
str
required
The host for the request (e.g. ‘api.cdp.coinbase.com’).
​
request_path
str
required
The path for the request (e.g. ‘/platform/v1/wallets//addresses’).
​
request_data
dict[str, Any]
required
The request data for the request (e.g. {"wallet_id": "1234567890"}).
# Example: Generate wallet JWT
from cdp.auth import generate_wallet_jwt, WalletJwtOptions

wallet_jwt = generate_wallet_jwt(
    WalletJwtOptions(
        wallet_auth_key="your-wallet-secret",
        request_method="POST",
        request_host="api.cdp.coinbase.com",
        request_path="/platform/v1/wallets/123/addresses",
        request_data={"wallet_id": "123"},
    )
)

​
HTTP Authentication

​
get_auth_headers

def get_auth_headers(options: GetAuthHeadersOptions) -> dict[str, str]:
Get authentication headers for HTTP requests.
​
options
GetAuthHeadersOptions
required
The options for generating auth headers.
​
return
dict[str, str]
Dictionary of authentication headers.

​
GetAuthHeadersOptions

​
api_key_id
str
required
The API key ID.
​
api_key_secret
str
required
The API key secret.
​
request_method
str
required
The HTTP method.
​
request_host
str
required
The request host.
​
request_path
str
required
The request path.
​
request_body
dict[str, Any]
Optional request body.
​
wallet_secret
str | None
Optional wallet secret.
​
source
str | None
Optional source identifier.
​
source_version
str | None
Optional source version.
​
expires_in
int | None
Optional JWT expiration time in seconds.
# Example: Get auth headers
from cdp.auth import get_auth_headers, GetAuthHeadersOptions

headers = get_auth_headers(
    GetAuthHeadersOptions(
        api_key_id="your-api-key-id",
        api_key_secret="your-api-key-secret",
        request_method="GET",
        request_host="api.cdp.coinbase.com",
        request_path="/platform/v1/accounts",
    )
)

​
WebSocket Authentication

​
get_websocket_auth_headers

def get_websocket_auth_headers(
    options: GetWebSocketAuthHeadersOptions
) -> dict[str, str]:
Get authentication headers for WebSocket connections.
​
options
GetWebSocketAuthHeadersOptions
required
The options for generating WebSocket auth headers.
​
return
dict[str, str]
Dictionary of authentication headers for WebSocket.

​
GetWebSocketAuthHeadersOptions

​
api_key_id
str
required
The API key ID.
​
api_key_secret
str
required
The API key secret.
# Example: Get WebSocket auth headers
from cdp.auth import get_websocket_auth_headers, GetWebSocketAuthHeadersOptions

ws_headers = get_websocket_auth_headers(
    GetWebSocketAuthHeadersOptions(
        api_key_id="your-api-key-id",
        api_key_secret="your-api-key-secret",
    )
)

​
Authenticated HTTP Client

​
Urllib3AuthClient

HTTP client that automatically adds authentication headers to requests. 
class Urllib3AuthClient:
    def __init__(
        self,
        options: Urllib3AuthClientOptions,
        base_url: str,
        debug: bool = False,
    ):
​
options
Urllib3AuthClientOptions
required
The authentication configuration options.
​
base_url
str
required
The base URL for all requests.
​
debug
bool
default:"False"
Whether to enable debug logging.

​
Urllib3AuthClientOptions

​
api_key_id
str
required
The API key ID.
​
api_key_secret
str
required
The API key secret.
​
wallet_secret
str | None
Optional wallet secret.
​
source
str | None
Optional source identifier.
​
source_version
str | None
Optional source version.
​
expires_in
int | None
Optional JWT expiration time in seconds.

​
request

def request(
    self,
    method: str,
    url: str,
    headers: dict[str, str] | None = None,
    body: dict[str, Any] | bytes | None = None,
    **kwargs: Any,
) -> urllib3.HTTPResponse:
Make an authenticated HTTP request.
​
method
str
required
The HTTP method.
​
url
str
required
The URL to request (relative or absolute).
​
headers
dict[str, str] | None
Optional additional headers.
​
body
dict[str, Any] | bytes | None
Optional request body (can be a dict for JSON or bytes).
​
**kwargs
Any
Additional arguments passed to urllib3.request().
​
return
urllib3.HTTPResponse
The HTTP response.
# Example: Using Urllib3AuthClient
from cdp.auth import Urllib3AuthClient, Urllib3AuthClientOptions

client = Urllib3AuthClient(
    options=Urllib3AuthClientOptions(
        api_key_id="your-api-key-id",
        api_key_secret="your-api-key-secret",
    ),
    base_url="https://api.cdp.coinbase.com/platform",
    debug=True,
)

response = client.request(
    method="GET",
    url="/v1/accounts",
)

print(response.data.decode("utf-8"))

​
Key Format Support

The authentication utilities support two types of private keys:

​
EC Keys (ES256)

PEM-formatted EC private keys: 
-----BEGIN EC PRIVATE KEY-----
MHcCAQEEIExamplePrivateKeyDataHere...
-----END EC PRIVATE KEY-----

​
Ed25519 Keys (EdDSA)

Base64-encoded Ed25519 private keys (64 bytes): 
xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx==
The library automatically detects the key type and uses the appropriate signing algorithm.

Build docs developers (and LLMs) love

Get started for freeTalk to us