API tokens

Personal API tokens let your scripts and AI tools act on your account. The REST API and the MCP server use the same tokens. Give each integration its own token, with only the abilities it needs.

Create a token#

1. Open API tokensIn the app, click API & MCP in the sidebar, then API tokens — or go to app.custodycommander.com/developers/tokens. Your email must be verified.
2. Name itSomething that tells you where it's used, like "My local AI assistant" or "Nightly backup script".
3. Set an expiryBy default a token expires in 30 days; pick another date, or tick No expiration.
4. Choose its abilitiesTick read and/or write for each area it needs, or Full access for everything (including the built-in assistant).
5. Copy itClick Create token, then Copy token. The full token is shown only once — store it somewhere safe before clicking I saved my token — close.

Token format#

Tokens start with cc_live_ followed by 43 characters. Send them in the Authorization header with exactly one space after Bearer:

Authorization: Bearer cc_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

We store only a hash of your token. The token list shows only its prefix (cc_live_ plus 7 characters); if you lose a token, revoke it and create a new one.

Abilities (scopes)#

Each ability is an area plus read (GET operations) or write (create, change, and delete operations). Write doesn't include read — tick both if the integration needs both.

Specific abilities don't grow: a token with evidence:read won't gain new areas as features are added. Only Full access covers future operations. Abilities grant an area of the app, including related data it displays — and your account's own sharing permissions always still apply.

Suggested sets#

Manage tokens#

Your tokens lists each token's name, status (Active, Expired, or Revoked), prefix, expiry, when it was last used, and its abilities.

• Edit changes the name, abilities, or expiry. The token itself stays the same, so nothing needs reconfiguring.
• Revoke stops the token immediately for new requests (requests already in progress may finish). It also revokes any tokens that token created. This can't be undone.

You can have up to 50 active tokens, each with up to 100 abilities.

Creating tokens from a token#

A token with tokens:write can create, edit, and revoke tokens through /api/v1/developer/tokens — useful for tools that hand out narrower tokens to sub-processes. The rules:

• A child token can't have abilities its parent lacks, and can't outlive its parent.
• A token can only manage itself and the tokens it (or its descendants) created, up to 8 levels deep.
• Revoking a token revokes every token beneath it.

Errors you might see#