Skip to main content

​
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"}]
  }'

​
Scopes

​
User Scopes

Available to all users:
ScopeDescription
chat:readRead chat history and conversations
chat:writeSend messages and create chat completions
models:readList available AI models, check quota status
knowledgebases:readList, view, and query knowledge bases
knowledgebases:writeCreate, modify, and delete knowledge bases
files:readDownload and list files
files:writeUpload and manage files

​
Admin-Only Scopes

Require Admin role. Non-admin users requesting these scopes will receive a 403 admin_scopes_required error.
ScopeDescription
agents:read / agents:writeAgent management
echo:read / echo:writeTranscriptions, recordings, and TTS synthesis
researcher:read / researcher:writeResearch sessions, search, analysis, and synthesis
docanalyzer:read / docanalyzer:writeDocument analysis sessions and results
sanitizer:read / sanitizer:writeSanitizer 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.
FieldConstraints
name1–100 characters, must be unique among active tokens
scopesAt least one from the allowed set
expires_in_days1–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

LimitValue
Max active tokens per user25
Max expiration365 days (configurable via PAT_MAX_EXPIRY_DAYS)
Token name length100 characters
Unique name per userActive tokens must have unique names

​
Error Codes

CodeHTTPMeaning
invalid_token_format401Token doesn’t match expected format
invalid_token401Token not found or secret mismatch
token_revoked401Token has been revoked
token_expired401Token has passed its expiration date
insufficient_scope403Token lacks the required scope for this endpoint
pat_not_allowed403API tokens cannot access this endpoint
admin_scopes_required403Requested scopes require Admin role
org_membership_required403API tokens require organization membership
api_access_not_available403API tokens require Team or Enterprise plan
duplicate_name409An active token with this name already exists
token_limit_reached429Maximum active tokens reached (25)
token_already_revoked400Cannot rotate a revoked token
token_expired400Cannot rotate an expired token