Skip to main content
Use API keys to authenticate requests to Circle’s platform. Circle provides two types of keys for different use cases: API keys for server-side access and client keys for frontend applications.

API key

Authenticate server-side requests to Circle’s RESTful APIs. Required for backend services.

Client key

Authenticate client applications with domain or app binding. Required for frontend SDKs.

​
Purpose of keys

The table below highlights the purpose of each key type.
PurposeAPI keyClient key
UsageAuthenticates server access to Circle’s RESTful APIsAuthenticates client applications with limited API access
Ideal forBackend services that call Circle’s APIsFrontend applications (web or mobile) using Circle’s client-side SDKs
Where to useServer-side API calls from secure backend environmentsClient applications bound to specific domains or app identifiers

​
Products and keys

The table below lists which Circle products require each key type.
Product/ServiceAPI keyClient key
Wallets: Modular✅ For retrieving transfer and UserOps data from Circle Indexing Service✅ For modular wallets SDKs
Wallets: User-Controlled✅❌
Wallets: Dev-Controlled✅❌
Contracts✅❌

​
API keys

An API key is a unique string used to authenticate and enable access to privileged operations on Circle’s APIs. It’s required for any RESTful API requests to Circle services. Without it, requests will fail.

​
Keep your API keys safe

API keys allow access to sensitive operations, so you must secure them.
  • Avoid public exposure: Never share API keys or include them in client-side code, public repositories, or other public mediums.
  • Manage securely: Use your Circle Developer account to generate and manage API keys. When generating a key, copy it exactly as displayed.
Losing control of your API key can result in financial loss.

​
API key authentication

Use the headers below to authenticate requests on testnet or mainnet.

​
Testnet authorization header example

authorization: Bearer TEST_API_KEY:ebb3ad72232624921abc4b162148bb84:019ef3358ef9cd6d08fc32csfe89a68d

​
Mainnet authorization header example

authorization: Bearer LIVE_API_KEY:ebb3ad72232624921abc4b162148bb84:019ef3358ef9cd6d08fc32csfe89a68d

​
Test authentication

To verify your API key setup, use the following curl command to retrieve wallets: 
curl --request GET \
     --url https://api.circle.com/v1/w3s/wallets \
     --header 'accept: application/json' \
     --header 'authorization: Bearer <API_KEY>'
A successful response looks like this: 
{
  "data": {
    "wallets": []
  }
}
An error response looks like this: 
{
  "code": 401,
  "message": "Malformed authorization. Are the credentials properly encoded?"
}

​
Client keys

A client key is a unique string used to authenticate and authorize API access for apps using Circle’s SDKs. A client key is linked to either a specific host domain (websites), bundle ID (iOS), or package name (Android). This restricts access to pre-configured apps.
A client key must be included in the headers of all modular wallets SDK API calls.

​
Best practices for client keys

Client keys enable access to sensitive application operations, so protecting them is critical. Follow these best practices:
  1. Use separate keys for each application: Create separate keys for web and mobile apps (iOS, Android) to prevent shared vulnerabilities.
  2. Monitor for misuse: Set up alerts for unusual activity, such as unexpected spikes in API calls, and use monitoring tools to detect anomalies.
  3. Rotate keys regularly: Regenerate client keys periodically and update them in your apps to reduce risk if a key is compromised.
  4. Store keys securely: Use secure storage options like Local Storage or Secure Storage for mobile apps, and avoid unnecessary exposure.
  5. Restrict access: Limit the scope of client keys by associating them with specific apps or domains to minimize potential misuse.