Assistant Tokens
The Assistant module exposes a single token route: a read-only listing of the API tokens scoped to one Assistant. It does not own token creation; new tokens are minted through the general token endpoint in the Auth API.
This route requires AI access (the AI module enabled on the tenant AND the
caller having AI access). The Assistant is then resolved through the
read_access model scope, so the caller only sees an Assistant it may read.
GET /api/assistants/{id}/tokens
List the API tokens scoped to an Assistant.
Authentication: Required (AI access)
Pre-blocks: ai.verify, then assistant.lookup(params.id) (which itself
re-runs ai.verify)
Response:
A HAL collection that embeds each token row under inf:assistant-token. Each
embedded row links to the global token route (/api/tokens/{id}) via self
and to its token type via inf:token-type. Rows are loaded through
Token.scope('read_access') filtered by assistantId.
Each row serializes its full Token record plus a freshly-signed JWT key. The
resource-type id columns (reportId, queryId, visualId, datasourceId,
datasetId) are omitted from the serialization. An assistant token has
type: "assistant", an assistantId tying it to the Assistant, and a
readOnly flag that defaults to false.
{
"_links": {
"self": {
"href": "https://informer.example.com/api/assistants/00000000-0000-4000-8000-000000000001/tokens"
}
},
"start": 0,
"count": 2,
"total": 2,
"_embedded": {
"inf:assistant-token": [
{
"_links": {
"self": {
"href": "https://informer.example.com/api/tokens/00000000-0000-4000-8000-000000000002"
},
"inf:token-type": {
"href": "https://informer.example.com/api/token-types/assistant"
}
},
"permissions": {
"edit": true,
"delete": true
},
"id": "00000000-0000-4000-8000-000000000002",
"type": "assistant",
"readOnly": false,
"notes": "Production API integration",
"restrict": null,
"host": null,
"cidr": null,
"data": null,
"requests": 0,
"blocked": 0,
"lastAccessedAt": null,
"expiresAt": null,
"createdAt": "2026-01-15T16:20:00.000Z",
"updatedAt": "2026-01-15T16:20:00.000Z",
"tenant": "acme",
"username": "admin",
"reportId": null,
"queryId": null,
"visualId": null,
"datasourceId": null,
"datasetId": null,
"appId": null,
"assistantId": "00000000-0000-4000-8000-000000000001",
"oauthClientId": null,
"key": "eyJhbGciOiJIUzI1NiJ9.example-token-1.signature"
},
{
"_links": {
"self": {
"href": "https://informer.example.com/api/tokens/00000000-0000-4000-8000-000000000003"
},
"inf:token-type": {
"href": "https://informer.example.com/api/token-types/assistant"
}
},
"permissions": {
"edit": true,
"delete": true
},
"id": "00000000-0000-4000-8000-000000000003",
"type": "assistant",
"readOnly": true,
"notes": "Read-only webhook callback",
"restrict": null,
"host": null,
"cidr": null,
"data": null,
"requests": 0,
"blocked": 0,
"lastAccessedAt": null,
"expiresAt": null,
"createdAt": "2026-01-15T16:20:00.000Z",
"updatedAt": "2026-01-15T16:20:00.000Z",
"tenant": "acme",
"username": "admin",
"reportId": null,
"queryId": null,
"visualId": null,
"datasourceId": null,
"datasetId": null,
"appId": null,
"assistantId": "00000000-0000-4000-8000-000000000001",
"oauthClientId": null,
"key": "eyJhbGciOiJIUzI1NiJ9.example-token-2.signature"
}
]
}
}
Token properties:
| Field | Type | Description |
|---|---|---|
id | string (UUID) | Token id |
type | string | Token type (assistant for assistant tokens) |
assistantId | string (UUID) | The Assistant this token is scoped to |
username | string | The user the token acts as |
readOnly | boolean | Whether the token grants read-only access |
notes | string | null | Free-text notes |
key | string | The signed JWT bearer token |
restrict / host / cidr | string | null | Access restrictions |
requests / blocked | integer | Usage counters |
lastAccessedAt / expiresAt | date | null | Access and expiry timestamps |
createdAt / updatedAt | date | Timestamps |
This listing returns each token's signed key. Treat the response like a list
of passwords: never log it, commit it to version control, or expose it in
client-side code.
Creating Assistant Tokens
The Assistant module has no token-creation route. To create a token scoped to an
Assistant, use the general token endpoint and set type to assistant:
POST /api/tokens
{
"type": "assistant",
"assistantId": "team:sales-assistant",
"notes": "Token for external API access"
}
See the Auth API - Tokens page for full token management documentation, including creation, rotation, and revocation. That endpoint lives in the auth area and is not captured on this page.
Security Considerations
- Scope limitation - Assistant tokens are tied to a single Assistant via
assistantId. - Read-only option - Set
readOnly: truewhen write access is not needed. - Rotation - Rotate tokens regularly for production use.
- Revocation - Delete a compromised token immediately through the Auth API.
Treat assistant tokens like passwords. Never commit them to version control or expose them in client-side code.