Carbon uses two credentials for two jobs:
Session JWT
Authorization: Bearer <jwt>
The wallet owner (via the Carbon app)
Account setup: enable subaccounts, create API keys, delegate permissions, set instant-action tokens
API key
x-api-key: ix.<hex>
Your app
Programmatic trading and reads
The model: a wallet owner uses a JWT to create API keys and grant them permission; the keys then do the day-to-day trading. Configure once with the JWT, run continuously with the key.
Account-management endpoints require a session JWT representing a signed-in wallet. You obtain it by signing in with your wallet in the Carbon app, then send it as a bearer token:
Authorization: Bearer eyJ…The token is bound to your wallet and expires; expired tokens return 401 and require a fresh sign-in. JWT-authenticated endpoints include /v1/account-auth/* and the API-key management routes.
For everything automated, use an API key:
ix.a1b2c3d4… (prefix "ix." + 64 hex characters)The
ix.prefix is a legacy identifier; it's still the live key format.
Send it in x-api-key:
GET /v1/positions/all?subaccountAddress=0x…&chainId=42161
x-api-key: ix.a1b2c3d4…Manage keys (JWT-authenticated):
Create
POST /v1/api-keys/create
List
GET /v1/api-keys/list
Rename
PUT /v1/api-keys/{id}
Revoke
DELETE /v1/api-keys/{id}
Inspect permissions
POST /v1/api-keys/list-permissions
The secret is shown once, at creation, and can't be retrieved again. Capture and store it securely; if lost, revoke and create a new one.
An API key can do nothing until the subaccount is enabled for API access and the key is granted permissions. That setup — via the Carbon app (recommended) or the API — is covered in Enabling API access.
Permissions: ALL, OPEN_POSITION, CLOSE_POSITION, CANCEL_POSITION, VIEW_DETAILS. A key lacking a permission is rejected with 403.
Never expose an API key in a browser, mobile app, or public repo. Keep it server-side — it's a bearer credential.
Scope narrowly — delegate only the permissions a key needs; avoid ALL.
One key per app/environment — makes rotation and revocation surgical.
Rotate and revoke — revocation is instant via DELETE /v1/api-keys/{id}.
Always HTTPS.
401
Missing/invalid/expired JWT, or unknown/revoked API key.
403
Authenticated, but the key lacks the delegated permission.

