Skip to main content

​
Overview

Coinbase Onramp and Offramp use session tokens for secure authentication. Session tokens are generated on your backend server using your CDP API keys and passed in the URL instead of including sensitive data like wallet addresses as query parameters.

​
How Session Tokens Work

Session tokens provide a secure way to initialize Onramp/Offramp experiences:
  1. Your backend server generates a session token using the CDP API
Security Requirements must be enforced: Your backend API that generates session tokens must implement proper security measures. See Security Requirements for complete implementation guidance.
  1. The token encapsulates user addresses, supported assets, and client IP
  2. You pass the token in the Onramp/Offramp URL
  3. The token expires after 5 minutes and can only be used once

​
Example URL Format

https://pay.coinbase.com/buy/select-asset?sessionToken=<token>&<other params>

​
Implementation Steps

​
Step 1: Create a CDP Secret API Key

Optional API Key File DownloadFor enhanced security, API key files are no longer automatically downloaded. If you need to reference your API key via file path in your code, click the Download API key button in the modal to save the key file. Otherwise, you can copy the key details directly from the modal and use them as environment variables (recommended for better security).
To generate session tokens, you’ll need a Secret API Key from the CDP Portal:
  1. Navigate to your project’s API Keys tab
  2. Select the Secret API Keys section
  3. Click Create API key
  4. Configure your key settings (IP allowlist recommended)
  5. Create your API key and securely store the details
Session tokens must be generated server-side, so you’ll need a Secret API Key (not a Client API Key).

​
Step 2: Set Up JWT Authentication

To generate session tokens, you need to authenticate with CDP using JWT Bearer tokens. Follow the CDP API key authentication guide to set up JWT generation.

​
Step 3: Generate Session Tokens

Use the Session Token API to generate tokens for each user session:
For complete API documentation including all parameters and response formats, see the Create Session Token API Reference.
You must include the true client IP of the end user when generating session tokens.
  • Extract the client IP from the network layer of the TCP request to your API
  • Do not trust HTTP headers like X-Forwarded-For — these can be easily spoofed
  • Include the client IP in the CDP API call for validation
curl -X POST 'https://api.developer.coinbase.com/onramp/v1/token' \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "addresses": [
      {
        "address": "0x4315d134aCd3221a02dD380ADE3aF39Ce219037c",
        "blockchains": ["ethereum", "base"]
      }
    ],
    "assets": ["ETH", "USDC"],
    "clientIp": "192.0.2.7"
  }'
Response: 
{
  "token": "ZWJlNDgwYmItNjBkMi00ZmFiLWIxYTQtMTM3MGI2YjJiNjFh",
  "channel_id": ""
}
See an example of how to generate a JWT and session token.

​
Step 4: Create Onramp/Offramp URLs

Use the session token to create your Onramp/Offramp URLs:
For detailed information about URL parameters and options, see:

​
Onramp URL Example

https://pay.coinbase.com/buy/select-asset?sessionToken=ZWJlNDgwYmItNjBkMi00ZmFiLWIxYTQtMTM3MGI2YjJiNjFh&defaultNetwork=base&presetFiatAmount=100

​
Offramp URL Example

https://pay.coinbase.com/v3/sell/input?sessionToken=ZWJlNDgwYmItNjBkMi00ZmFiLWIxYTQtMTM3MGI2YjJiNjFh&partnerUserId=user123&redirectUrl=https://yourapp.com/success

​
Session Token Properties

  • Expiration: Session tokens expire after 5 minutes
  • Single-use: Each token can only be used once
  • Server-side generation: Must be generated on your backend server

​
Support and Resources

⌘I