API Keys

Ragty provides personal API keys for MCP and public machine integrations. Keys are created from Settings → API Keys in the authenticated web application.

Key Types

Type	Scope
Personal	Inherits the owner's permissions in the active tenant
Dataset-scoped	Records one or more selected tenant datasets for integrations that enforce that scope

Dataset selection never grants access the owner does not already have.

Security Model

Tokens use the ragty-... prefix and 24 random bytes encoded as hexadecimal.
Only an HMAC-SHA256 hash is stored; the raw token cannot be recovered.
The raw token is displayed once in the create response.
Keys are user-owned and tenant-scoped.
Optional expiration is enforced during key resolution.
Revocation deletes the stored key record immediately.

Store keys in a secret manager. Do not place them in source control, images, logs, or shared desktop configuration.

Administration Endpoints

Browser code uses the same-origin frontend proxy:

Method	Browser path	Description
`POST`	`/admin-api/keys`	Create a key
`GET`	`/admin-api/keys`	List the current user's keys in the active tenant
`DELETE`	`/admin-api/keys/{key_id}`	Revoke a key by UUID

The frontend forwards these requests to backend /admin-api/v1/keys. That backend prefix is internal and should not be exposed as a third-party API. Key administration requires the authenticated browser/JWT flow; an API key cannot create another API key.

Create a Key

{
  "name": "Knowledge Agent",
  "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; default is empty
`scope_type`	string	Yes	`personal` or `dataset`
`dataset_ids`	string[]	For dataset scope	At least one dataset from the active tenant
`expires_at`	datetime/null	No	ISO 8601 expiry; `null` means no expiry

Successful creation returns HTTP 201:

{
  "token": "ragty-REDACTED",
  "key_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "Knowledge Agent",
  "scope_type": "dataset",
  "datasets": [
    {"id": "550e8400-e29b-41d4-a716-446655440000", "name": "Company Policies"}
  ],
  "expires_at": "2026-12-31T23:59:59+00:00",
  "created_at": "2026-08-23T12:00:00+00:00"
}

The token value is never returned by list operations.

Use a Key

Send the token as a Bearer credential:

Authorization: Bearer ragty-YOUR_API_KEY

Personal keys are accepted by MCP at /mcp/.

Personal keys are not a substitute for the browser session and are not accepted as credentials for arbitrary /admin-api/* operations.

Dialog API Keys

Dialog API keys are separate credentials bound to one dialog. They are created from that dialog's administration UI and are accepted by /api/v1/chat/completions. They do not use the personal-key management page or grant MCP access.

Credential Migration

Provider credentials and legacy dialog tokens can be migrated with:

cd backend
uv run python scripts/migrate_security_storage.py

Provider credentials are encrypted. Legacy raw dialog tokens are invalidated because they cannot be converted safely; issue replacements after migration.

23 August 2026