API Tokens

Personal Access Tokens (PATs) are the long-lived credential your scripts, notebooks, CI jobs, and integrations use to call the co-mind.ai API. This page covers why PATs exist alongside the interactive JWT session, which scopes are available, and how to create, rotate, and revoke tokens.

API tokens require a Team or Enterprise plan with API access enabled, and the user must belong to an organization.

Why JWT then PAT

You log in to get a session JWT — a short-lived token (one hour by default) issued from POST /v1/auth/login or an SSO exchange. The JWT is perfect for interactive use, like signing in to the app or exploring the API from a terminal, but it expires and needs refreshing. Not what you want inside a cron job or a customer-facing integration. A Personal Access Token (PAT) is what you mint from that session to hand off to automation. It’s long-lived (up to a year), scope-limited (you pick exactly what it can do), and tied to the workspace your session was scoped to at creation time. The typical flow:

Sign in — receive a session JWT
Choose the workspace you want the token to belong to (if you have more than one, switch to it on the JWT session)
Mint a PAT with the scopes your automation needs
Use the PAT for every API request going forward
Rotate on a schedule; revoke immediately if you suspect compromise

The API Walkthrough walks this end-to-end with real curl calls.

Using a PAT

Include the token in the Authorization header:

Authorization: Bearer cmnd_<token-id>.<secret>

Tokens start with the cmnd_ prefix and work anywhere a JWT Bearer token is accepted for the same operations.

curl {BASE_URL}/v1/chat/completions \
  -H "Authorization: Bearer cmnd_your-token-here" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "llama3.2:3b",
    "messages": [{"role": "user", "content": "Hello"}]
  }'

curl {BASE_URL}/v1/models \
  -H "Authorization: Bearer cmnd_your-token-here"

Scopes

Scopes are permissions attached to the token — a PAT can only perform operations covered by its scopes. Request only what your automation actually needs; smaller scope means smaller blast radius if the token leaks.

Scope	Description
`chat:read`	Read chat history and conversations
`chat:write`	Send messages and create chat completions
`models:read`	List available AI models, check quota status
`knowledgebases:read`	List, view, and query knowledge bases
`knowledgebases:write`	Create, modify, and delete knowledge bases
`files:read`	Download and list files
`files:write`	Upload and manage files

Administrators have additional scopes covering tenant and platform-configuration APIs. Those admin scopes and endpoints are not part of the public reference — see Tenant Admin API and System Admin API for how to request access.

Discover the scopes available to you

The exact scope list your account can request is available via a JWT-authenticated call:

curl {BASE_URL}/v1/api-tokens/scopes \
  -H "Authorization: Bearer $JWT"

{
  "scopes": [
    "knowledgebases:read",
    "knowledgebases:write",
    "chat:read",
    "chat:write",
    "models:read",
    "files:read",
    "files:write"
  ]
}

This endpoint requires JWT authentication — PATs cannot access it.

Token management

Management endpoints require JWT authentication. A PAT cannot manage other PATs (a stolen PAT can be used for its scopes, but cannot create new tokens or extend its own lifetime).

Create a token

POST /v1/api-tokens

curl -X POST {BASE_URL}/v1/api-tokens \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CI/CD Pipeline",
    "scopes": ["knowledgebases:read", "chat:write"],
    "expires_in_days": 90
  }'

Response (201):

{
  "token": "cmnd_550e8400-e29b-41d4-a716-446655440000.abc123...",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "CI/CD Pipeline",
  "scopes": ["knowledgebases:read", "chat:write"],
  "created_at": "2026-01-15T10:30:00.000Z",
  "expires_at": "2026-04-15T10:30:00.000Z"
}

The token field is returned only once. Store it securely.

Field	Constraints
`name`	1–100 characters, must be unique among your active tokens
`scopes`	At least one from the allowed set
`expires_in_days`	1–365

List tokens

GET /v1/api-tokens Returns metadata for all your tokens. No secrets are included.

{
  "tokens": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "CI/CD Pipeline",
      "scopes": ["knowledgebases:read", "chat:write"],
      "created_at": "2026-01-15T10:30:00.000Z",
      "expires_at": "2026-04-15T10:30:00.000Z",
      "last_used_at": "2026-02-01T08:00:00.000Z",
      "is_expired": false,
      "is_revoked": false
    }
  ]
}

Revoke a token

DELETE /v1/api-tokens/{id} Immediately invalidates the token. This cannot be undone. Idempotent — revoking an already-revoked token returns 204.

Rotate a token

POST /v1/api-tokens/{id}/rotate Revokes the old token and creates a new one with the same name and scopes. The new token inherits the remaining expiry of the old token (capped at 365 days).

Cannot rotate a revoked or expired token.

Limits

Limit	Value
Max active tokens per user	25
Max expiration	365 days
Token name length	100 characters
Unique name per user	Active tokens must have unique names

Error codes

Complete error code reference

Code	HTTP	Meaning
`invalid_token_format`	401	Token doesn’t match expected format
`invalid_token`	401	Token not found or secret mismatch
`token_revoked`	401	Token has been revoked
`token_expired`	401	Token has passed its expiration date
`insufficient_scope`	403	Token lacks the required scope for this endpoint
`pat_not_allowed`	403	API tokens cannot access this endpoint
`org_membership_required`	403	API tokens require organization membership
`api_access_not_available`	403	API tokens require Team or Enterprise plan
`duplicate_name`	409	An active token with this name already exists
`token_limit_reached`	429	Maximum active tokens reached (25)

Getting Started

Guides

API Walkthrough

Why JWT then PAT

Using a PAT

Scopes

Discover the scopes available to you

Token management

Create a token

List tokens

Revoke a token

Rotate a token

Limits

Error codes

​Why JWT then PAT

​Using a PAT

​Scopes

​Discover the scopes available to you

​Token management

​Create a token

​List tokens

​Revoke a token

​Rotate a token

​Limits

​Error codes

Why JWT then PAT

Using a PAT

Scopes

Discover the scopes available to you

Token management

Create a token

List tokens

Revoke a token

Rotate a token

Limits

Error codes