Authentication

Carbon uses two credentials for two jobs:

Credential	Header	Held by	Used for
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.

Session JWT

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.

API keys

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):

Action	Endpoint
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.

Granting a key access to a subaccount

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.

Best practices

• 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.

Failures

Status	Meaning
401	Missing/invalid/expired JWT, or unknown/revoked API key.
403	Authenticated, but the key lacks the delegated permission.