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

# Tokens

> Endpoints to manage API tokens

Endpoints to manage API access tokens.

## GET /tenants/{slug}/tokens

List all tenant tokens.

**Required scope:** `tokens:read`

### Request

```bash theme={null}
curl https://api.animam.ai/tenants/my-company/tokens \
  -H "Authorization: Bearer ak_your_token"
```

### Response

```json theme={null}
{
  "tokens": [
    {
      "id": "tok_abc123",
      "name": "Production API",
      "prefix": "ak_prod_",
      "scopes": ["corpus:read", "corpus:write"],
      "createdAt": "2024-01-15T10:30:00Z",
      "lastUsedAt": "2024-01-25T14:22:00Z",
      "expiresAt": null
    },
    {
      "id": "tok_xyz789",
      "name": "Analytics readonly",
      "prefix": "ak_analytics_",
      "scopes": ["conversations:read"],
      "createdAt": "2024-01-20T08:00:00Z",
      "lastUsedAt": null,
      "expiresAt": "2024-12-31T23:59:59Z"
    }
  ]
}
```

<Note>
  The full token is never returned. Only the prefix is visible.
</Note>

## POST /tenants/{slug}/tokens

Create a new token.

**Required scope:** `tokens:write`

### Request

```bash theme={null}
curl -X POST https://api.animam.ai/tenants/my-company/tokens \
  -H "Authorization: Bearer ak_your_token" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CI/CD Pipeline",
    "scopes": ["corpus:read", "corpus:write"],
    "expiresAt": "2025-01-01T00:00:00Z"
  }'
```

### Body

| Field       | Type      | Required | Description                |
| ----------- | --------- | -------- | -------------------------- |
| `name`      | string    | Yes      | Descriptive name           |
| `scopes`    | string\[] | Yes      | List of scopes             |
| `expiresAt` | string    | No       | Expiration date (ISO 8601) |

### Response

```json theme={null}
{
  "id": "tok_new456",
  "name": "CI/CD Pipeline",
  "token": "ak_live_abc123xyz789...",
  "scopes": ["corpus:read", "corpus:write"],
  "createdAt": "2024-01-25T10:30:00Z",
  "expiresAt": "2025-01-01T00:00:00Z"
}
```

<Warning>
  The `token` field is only returned at creation. Store it immediately.
</Warning>

## DELETE /tenants/{slug}/tokens/{id}

Revoke a token.

**Required scope:** `tokens:write`

### Request

```bash theme={null}
curl -X DELETE https://api.animam.ai/tenants/my-company/tokens/tok_abc123 \
  -H "Authorization: Bearer ak_your_token"
```

### Response

```json theme={null}
{
  "deleted": true,
  "id": "tok_abc123"
}
```

## Available scopes

| Scope                | Description          |
| -------------------- | -------------------- |
| `corpus:read`        | Read corpus          |
| `corpus:write`       | Modify corpus        |
| `conversations:read` | View conversations   |
| `settings:read`      | Read tenant settings |
| `settings:write`     | Modify settings      |
| `tokens:read`        | List tokens          |
| `tokens:write`       | Create/delete tokens |
| `*`                  | Full access (admin)  |

## Best practices

### Naming

Use descriptive names:

* `Production API` - Main token
* `CI/CD Corpus Sync` - Specific integration
* `Analytics Dashboard` - Read-only access

### Minimal scopes

```json theme={null}
// Bad: too many permissions
{ "scopes": ["*"] }

// Good: minimal permissions
{ "scopes": ["corpus:read"] }
```

### Expiration

For temporary tokens (CI/CD, tests):

```json theme={null}
{
  "name": "Temporary test token",
  "scopes": ["corpus:read"],
  "expiresAt": "2024-02-01T00:00:00Z"
}
```

### Rotation

Review and rotate your tokens regularly:

1. Create a new token
2. Update your integrations
3. Verify everything works
4. Delete the old token