Authentication

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 follow the format cc_ followed by 64 lowercase hexadecimal characters:

cc_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2

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.

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.

If authentication fails, the API returns a 401 Unauthorized:

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or missing API key."
  }
}

If you authenticate successfully but your key lacks the required scope, you’ll receive 403 Forbidden:

{
  "error": {
    "code": "forbidden",
    "message": "This key does not have the required scope."
  }
}

See Errors for the full error reference.