Overview
All API endpoints are authenticated using API keys. Pass your key as a Bearer token in the Authorization header.
curl https://carboncopy.inc/api/v1/portfolio \
-H "Authorization: Bearer cc_your_key_here"
API Keys
API keys follow the format cc_ followed by 64 lowercase hexadecimal characters:
cc_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2
Creating a key
- Log in to Carboncopy
- Navigate to Settings → API Keys
- Click Create Key, choose a name and scopes
- Copy the key — it’s shown exactly once and cannot be retrieved later
Scopes
Every key is issued with a set of scopes that control what it can access. Always issue keys with the minimum scopes your use-case requires.
| Scope | Values | Controls |
|---|
portfolio | none, read | View portfolio summary, history, and positions |
traders | none, read, write | List/view traders (read); follow/edit/unfollow (write) |
orders | none, read, write | View orders (read); future order mutations (write) |
markets | none, read | Market data access (coming soon) |
account | none, read | View account information |
write scope implies read for the same resource. You don’t need to grant both.
Key lifecycle
- Maximum 10 active keys per account.
- Keys can have an optional expiry timestamp.
- Revoke a key anytime from Settings → API Keys.
Security best practices
Never commit API keys to source control. Use environment variables or a secrets manager.
- Rotate regularly — set an expiry and automate rotation in production.
- Narrow scopes — monitoring bots only need
portfolio:read; they don’t need traders:write.
- One key per service — easier to audit, easier to revoke if compromised.
- Revoke immediately if a key is exposed.
Error responses
If authentication fails, the API returns a 401 Unauthorized:
{
"error": {
"code": "unauthorized",
"message": "Invalid or missing API key."
}
}
403 Forbidden:
{
"error": {
"code": "forbidden",
"message": "This key does not have the required scope."
}
}
