Introduction
Looking for Coinbase App authentication?This page covers authentication for Coinbase Developer Platform (CDP) APIs for building onchain apps. If you’re looking to access consumer Coinbase App accounts, see the Coinbase App API Authentication documentation.
- 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 API Key: For all client-side communication (i.e., JSON-RPC APIs).
Client API Key
The Client API Key is designed specifically for client-side applications. This key:- Is present within your RPC endpoint URL (i.e.,
https://api.developer.coinbase.com/rpc/v1/base/<MY-CLIENT-API-KEY>
) - Authenticates JSON-RPC requests from browser-based applications and mobile apps
- Is safe to include in client-side code
- Has limited functionality by design
- Can be easily rotated if needed
1. Create Client API Key
To create a Client API Key:- Navigate to your API Keys dashboard.
- Select your desired project from the top drop-down.
- Select the Client API Key tab.
- Copy the generated key.
- Export as an environment variable:
Click the Rotate button to expire this key and generate a new one.
2. Authenticate
To authenticate your client-side code, include it with your JSON-RPC request:Secret API Key
The Secret API Key is required for all server-to-server communication with CDP APIs. This key:- Is used to generate a Bearer Token (JWT), which authenticates your CDP project ownership
- Is used in the
Authorization
header of your request - Is required as the base layer of authentication for all server endpoints
- Must be kept secure and never exposed in client-side code
- Can be configured with IP allowlists and more granular permissions
1. Create Secret API Key
To create a Secret API Key:- Navigate to your API Keys dashboard.
- Select your desired project from the top drop-down.
- Select the Secret API Keys tab.
- Click Create API key and name your key.
- Optional: Configure additional settings
- IP allowlist
- Permission restrictions
- Signature algorithm (Ed25519 recommended)
- Click Create & download.
To regenerate a Secret API key, click Configure to delete and recreate the key.
2. Generate Bearer Token
Bearer Tokens (JWTs) are required for server-to-server communication only, are included in yourAuthorization
header, and are generated using your Secret API Key.
Use our SDK for easier authenticationThe CDP SDK automatically handles generation of Bearer Tokens for you, streamlining the process of making requests to all of our REST endpoints.
- Set up your environment for Bearer Token generation by configuring environment variables and installing dependencies
- Export your generated Bearer Token as an environment variable
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.
Environment setup
To begin, export the following environment variables:Generate Bearer Token (JWT) and export
First, install the CDP SDK:Create a new file for JWT generation code:Finally, run the script to generate the JWT output and export it as an environment variable:
main.js
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.
3. Authenticate
Use our SDK for easier authenticationThe CDP SDK automatically handles authentication for you, streamlining the process of making requests to all of our REST endpoints.
Wallet Secret
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
andDELETE
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)
- Is never visible to Coinbase
1. Create Wallet Secret
To create a Wallet Secret:- Navigate to your Server Wallet dashboard.
- 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.
2. Generate Wallet Token
Wallet Tokens (Wallet Authentication JWTs) are required for any server-to-server communication that requires aX-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.
- 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
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:
- The request body matches exactly what was signed
- The endpoint URI matches exactly what was signed
- The JWT was signed with the correct Wallet Secret
Environment setup
To begin, export the following environment variables:Generate Wallet Token (JWT) and export
First, install required dependencies:Create a new file to generate your Wallet Token:Finally, run the script to generate the JWT output and export it as an environment variable:
generate_wallet_jwt.js
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.3. Authenticate
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.
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
What to read next
- Security Best Practices: Learn how to secure your API keys and other sensitive information.
- CDP API Keys: Learn how to create and manage your API keys.
- JWT Authentication: More information on JWT authentication.
- CDP cURL: Learn how to use our CLI tool to interact with the CDP API.
- Postman Files: Download our Postman collection and environment files to get started.