> ## Documentation Index
> Fetch the complete documentation index at: https://docs.co-mind.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# API Tokens

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

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

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

<CodeGroup>
  ```bash Chat Completion theme={null}
  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"}]
    }'
  ```

  ```bash List Models theme={null}
  curl https://your-instance/v1/models \
    -H "Authorization: Bearer cmnd_your-token-here"
  ```
</CodeGroup>

## 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

```bash theme={null}
curl https://your-instance/v1/api-tokens/scopes \
  -H "Authorization: Bearer $JWT"
```

```json theme={null}
{
  "scopes": [
    "knowledgebases:read",
    "knowledgebases:write",
    "chat:read",
    "chat:write",
    "models:read",
    "files:read",
    "files:write"
  ],
  "is_admin": false
}
```

<Info>
  This endpoint requires JWT authentication — PATs cannot access it.
</Info>

## 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`

```bash theme={null}
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):**

```json theme={null}
{
  "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"
}
```

<Warning>
  The `token` field is returned **only once**. Store it securely.
</Warning>

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

```json theme={null}
{
  "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).

<Note>
  Cannot rotate a revoked or expired token. Organization membership and plan tier are rechecked at rotation time.
</Note>

## 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

<Accordion title="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                   |
</Accordion>