Coinbase Developer Platform (CDP) uses three distinct types of authentication keys, each serving a specific purpose:
Server requests:
These keys should be stored securely, and used only by trusted back-end services:
Secret API Key: For all server-to-server communication (i.e., REST APIs).
Wallet Secret: Additional requirement for any server-to-server communication that involves sensitive wallet operations (i.e., signing transactions via REST APIs).
Client requests:
These keys are designed for client-side communication, and are safe to include in end-user code:
Client API Key: For all client-side communication (i.e., JSON-RPC APIs).
Bearer Tokens (JWTs) are required for server-to-server communication only, are included in your Authorization header, and are generated using your Secret API Key.
Use our SDK for easier authentication
The CDP SDK automatically handles generation of Bearer Tokens for you, streamlining the process of making requests to all of our REST endpoints.
For REST API users, continue reading to:
Set up your environment for Bearer Token generation by configuring environment variables and installing dependencies
Export your generated Bearer Token as an environment variable
Show More on JWTs
A JWT is a compact, self-contained, stateless token format used to securely transmit API keys as a JSON object for authentication with the CDP API. They are typically included in the Authorization header of your request.
Never include Secret API key information in your code.
Instead, securely store it and retrieve it from an environment variable, a secure database, or other storage mechanism intended for highly-sensitive parameters.
const { generateJwt } = require("@coinbase/cdp-sdk/auth");const main = async () => { // Generate the JWT using the CDP SDK const token = await generateJwt({ apiKeyId: process.env.KEY_NAME, apiKeySecret: process.env.KEY_SECRET, requestMethod: process.env.REQUEST_METHOD, requestHost: process.env.REQUEST_HOST, requestPath: process.env.REQUEST_PATH, expiresIn: 120 // optional (defaults to 120 seconds) }); console.log(token);};main();
Finally, run the script to generate the JWT output and export it as an environment variable:
Copy
Ask AI
export JWT=$(node main.js)echo $JWT
Bearer Tokens are valid for 2 minutes by default. After 2 minutes, you will need to generate a new Bearer Token (JWT) to ensure uninterrupted access to the CDP APIs.
If you are experiencing issues, please make sure your machine’s clock is accurate.
The Wallet Secret is an additional layer of security that’s required for any server-to-server requests that involve sensitive wallet write operations to the EVM and Solana APIs. This key:
Is used to generate a Wallet Token (JWT), which authenticates your wallet ownership
Is used in the X-Wallet-Auth header of your request
Is required for sensitive wallet operations (i.e., POST and DELETE requests), such as signing a transaction
Should be treated like the password to your onchain wallet
Is generated by CDP’s Trusted Execution Environment (TEE)
Ensure your desired project is selected from the top drop-down.
In the Wallet Secret section, click the Generate button.
Save the secret in a secure location - you won’t be able to view it again.
Your Wallet Secret is a secret that, when combined with your Secret API Key, can be used to sign transactions and messages. It is generated by CDP’s Trusted Execution Environment (TEE), and is never visible to Coinbase. Secure it as you would a password, and never share it or expose it in client-side code.
Wallet Tokens (Wallet Authentication JWTs) are required for any server-to-server communication that requires a X-Wallet-Auth header, and are generated using your Wallet Secret.
Use our SDK for easier authentication
The CDP SDK automatically handles generation of Wallet Authentication JWTs for you, streamlining the process of making requests to all of our REST endpoints.
For REST API users, continue reading to:
Set up your environment for Wallet Authentication JWT generation by configuring environment variables and installing dependencies
Export your generated Wallet Authentication JWT as an environment variable
More on Wallet Authentication JWTs
The Wallet Authentication JWT provides an additional layer of security for sensitive wallet operations. It is verified by CDP’s Trusted Execution Environment (TEE) to ensure that:
To begin, export the following environment variables:
Copy
Ask AI
# Your Wallet Secret from the CDP Portalexport WALLET_SECRET="your-wallet-secret"# The endpoint you're callingexport REQUEST_METHOD="POST"export REQUEST_PATH="/platform/v2/evm/accounts/0x742d35Cc6634C0532925a3b844Bc454e4438f44e/sign/transaction"export REQUEST_HOST="api.cdp.coinbase.com"# The exact request body you'll sendexport REQUEST_BODY='{"transaction": "0x1234567890123456789012345678901234567890"}'
Complete the remaining setup steps for JWT generation below according to your language choice.
Finally, run the script to generate the JWT output and export it as an environment variable:
Copy
Ask AI
# Generate and export the JWTexport WALLET_AUTH_JWT=$(node generate_wallet_jwt.js)echo $WALLET_AUTH_JWT
Wallet Tokens are valid for 1 minute. After 1 minute, you will need to generate a new one.
If you are experiencing issues, please make sure your machine’s clock is accurate.
The req claim in the wallet JWT is still supported for backwards compatibility with the CDP SDK, but reqHash is now the preferred way to include request body information.
The req claim will eventually be deprecated - we recommend using reqHash for all new implementations.
Use our SDK for easier authentication
The CDP SDK automatically handles authentication for you, streamlining the process of making requests to all of our REST endpoints.
For endpoints that require wallet authentication (marked with the X-Wallet-Auth header requirement), you must include both:
The standard Bearer token in the Authorization header
The Wallet Authentication JWT in the X-Wallet-Auth
For example, to sign a transaction:
Copy
Ask AI
# First construct the full API endpoint using our env varsexport API_ENDPOINT="https://${REQUEST_HOST}${REQUEST_PATH}"# Make the authenticated request using both JWT tokenscurl -L -X ${REQUEST_METHOD} "${API_ENDPOINT}" \ -H "Authorization: Bearer ${JWT}" \ -H "X-Wallet-Auth: ${WALLET_AUTH_JWT}" \ -H "Content-Type: application/json" \ -H "Accept: application/json" \ -d "${REQUEST_BODY}"
This example uses the environment variables we set earlier.