API Keys

Users can create personal API keys via Settings → API Keys for programmatic access to the platform.

Key Types

Type	Description
Personal	Inherits all user permissions within the tenant
Dataset-scoped	Restricted to selected datasets only (min. 1 dataset required)

Security Model

Keys are stored as HMAC-SHA256 hashes — non-reversible, cannot be recovered
The raw key is shown once at creation time — save it immediately
Keys are identified by a random UUID — no part of the token is exposed in the database or UI
Optional expiration date — expired keys are rejected at authentication time
Keys are tenant-scoped and user-owned — a key only works within its tenant context

API Endpoints

Method	Path	Description
`POST`	`/keys`	Create a new API key
`GET`	`/keys`	List user's keys in current tenant
`DELETE`	`/keys/{key_id}`	Revoke a key by its UUID

All endpoints require authentication via Authorization: Bearer <jwt>.

Create Key

Request:

{
  "name": "CI/CD Pipeline",
  "scope_type": "dataset",
  "dataset_ids": ["550e8400-e29b-41d4-a716-446655440000"],
  "expires_at": "2026-12-31T23:59:59Z"
}

Field	Type	Required	Description
`name`	string	No	Human-readable label
`scope_type`	string	Yes	`"personal"` or `"dataset"`
`dataset_ids`	string[]	Conditional	Required when `scope_type` is `"dataset"`
`expires_at`	datetime	No	ISO 8601 expiry (null = never expires)

Response:

{
  "token": "ragty-1ca70751e6ca17a4ae4a5c4fa3...",
  "key_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "CI/CD Pipeline",
  "scope_type": "dataset",
  "datasets": [
    {"id": "550e8400-...", "name": "Company Policies"}
  ],
  "expires_at": "2026-12-31T23:59:59+00:00",
  "created_at": "2026-06-12T07:12:01+00:00"
}

List Keys

Response:

[
  {
    "key_id": "a1b2c3d4-...",
    "name": "CI/CD Pipeline",
    "scope_type": "dataset",
    "datasets": [{"id": "...", "name": "Company Policies"}],
    "expires_at": "2026-12-31T23:59:59+00:00",
    "created_at": "2026-06-12T07:12:01+00:00"
  }
]

Note: The raw token is never returned in list responses.

Usage

Use the key as a Bearer token in the Authorization header:

Authorization: Bearer ragty-1ca70751e6ca17a4ae4a5c4fa3...

Works with:

MCP server (/mcp/)
OpenAI-compatible chat API (/v1/chat/completions)
Any authenticated endpoint

Credential Migration

Legacy dialog API tokens (raw values stored in database) can be migrated with:

cd backend
uv run python scripts/migrate_security_storage.py

This encrypts provider credentials and invalidates legacy plaintext dialog tokens. New keys must be issued to affected clients.

12 June 2026