API Tokens

API tokens (Personal Access Tokens) provide programmatic access to the co-mind.ai API with fine-grained scopes.

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

Authentication with PATs

Include your 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.

curl https://your-instance/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 https://your-instance/v1/models \
  -H "Authorization: Bearer cmnd_your-token-here"

Scopes

User Scopes

Available to all users:

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

Admin-Only Scopes

Require Admin role. Non-admin users requesting these scopes will receive a 403 admin_scopes_required error.

Scope	Description
`agents:read` / `agents:write`	Agent management
`echo:read` / `echo:write`	Transcriptions, recordings, and TTS synthesis
`researcher:read` / `researcher:write`	Research sessions, search, analysis, and synthesis
`docanalyzer:read` / `docanalyzer:write`	Document analysis sessions and results
`sanitizer:read` / `sanitizer:write`	Sanitizer policies and testing

Discover Available Scopes

curl https://your-instance/v1/api-tokens/scopes \
  -H "Authorization: Bearer $JWT"

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

This endpoint requires JWT authentication — PATs cannot access it.

Token Management

All management endpoints require JWT authentication. PATs attempting to access these endpoints receive a 403 pat_not_allowed error.

Create a Token

POST /v1/api-tokens

curl -X POST https://your-instance/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": "2025-01-15T10:30:00.000Z",
  "expires_at": "2025-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 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": "2025-01-15T10:30:00.000Z",
      "expires_at": "2025-04-15T10:30:00.000Z",
      "last_used_at": "2025-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. Organization membership and plan tier are rechecked at rotation time.

Limits

Limit	Value
Max active tokens per user	25
Max expiration	365 days (configurable via `PAT_MAX_EXPIRY_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
`admin_scopes_required`	403	Requested scopes require Admin role
`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)
`token_already_revoked`	400	Cannot rotate a revoked token
`token_expired`	400	Cannot rotate an expired token

Getting Started

Guides

Authentication with PATs

Scopes

User Scopes

Admin-Only Scopes

Discover Available Scopes

Token Management

Create a Token

List Tokens

Revoke a Token

Rotate a Token

Limits

Error Codes

​Authentication with PATs

​Scopes

​User Scopes

​Admin-Only Scopes

​Discover Available Scopes

​Token Management

​Create a Token

​List Tokens

​Revoke a Token

​Rotate a Token

​Limits

​Error Codes

Authentication with PATs

Scopes

User Scopes

Admin-Only Scopes

Discover Available Scopes

Token Management

Create a Token

List Tokens

Revoke a Token

Rotate a Token

Limits

Error Codes