Token Management API
API tokens for authenticating Zipf AI requests. Uses Bearer authentication with optional permission scoping.
Security: Never commit tokens. Rotate every 90 days. Use different tokens per environment.
GET /api/v1/tokens
List all tokens with usage stats. Returns tokens[] with id, token_name, token_prefix, permissions, rate_limit_per_hour, rate_limit_per_day, is_active, last_used_at, created_at, expires_at.
POST /api/v1/tokens
Create a new token. The full token is only shown once — store it immediately.
| Parameter | Type | Required | Description |
|---|---|---|---|
token_name | string | Yes | Descriptive name (max 255 chars) |
permissions | string[] | No | Scopes (default: all). Options: search, crawl, sessions, workflow |
Response: token (full value, shown once), token_id, token_name, token_prefix, permissions.
PATCH /api/v1/tokens/{id}
Update token name or permissions.
| Parameter | Type | Description |
|---|---|---|
name | string | Update display name |
permissions | object | {search: bool, crawl: bool} |
GET /api/v1/tokens/{id}/logs
Usage logs (last 100 requests). Each entry: endpoint, method, status_code, response_time_ms, credits_used, ip_address, user_agent, request_metadata.
DELETE /api/v1/tokens/{id}
Revoke a token (soft delete). Cannot revoke the token used for the current request.
Token Permissions
| Permission | Allows |
|---|---|
search | Search operations (including decomposition) |
crawl | Web crawling operations |
sessions | Session creation and management |
workflow | Workflow creation and monitoring |
Default: all permissions if none specified.
Token Lifecycle
Creation → Active Use → Monitoring → Rotation (create new, update apps, revoke old) → Revocation