API Key Authentication

API keys are the primary authentication mechanism for CLI operators, daemon workers, and programmatic integrations. Rensei uses a unified rsk_live_* key format with scope-based access control.

Key format

All new API keys follow the format rsk_live_<random>. The prefix encodes:

rsk - Rensei service key
live - production environment (keys issued against your live workspace)
<random> - cryptographically random suffix

The legacy POST /api/org/api-keys endpoint is deprecated and emits a Deprecation: true response header. Use POST /api/org/[orgId]/keys as the canonical path.

Creating an API key

Navigate to Settings > API Keys in the Rensei dashboard.
Click Create API Key.
Select the key type:
- User key - scoped to your user identity; inherits your org access.
- Worker registration key - used by daemon workers to register and receive a runtime JWT.
Choose the scopes required for your use case.
Copy the key immediately - it is only shown once.

# List existing keys
af org api-keys list

# Create a new worker registration key
af org api-keys create --type worker_registration --name "my-daemon"

curl -X POST https://app.rensei.ai/api/org/$ORG_ID/keys \
  -H "Authorization: Bearer rsk_live_<admin_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "ci-pipeline",
    "keyType": "user",
    "scopes": ["sessions:read", "workflows:read"]
  }'

Response:

{
  "keyId": "key_01abc...",
  "token": "rsk_live_...",
  "name": "ci-pipeline",
  "keyType": "user",
  "scopes": ["sessions:read", "workflows:read"],
  "createdAt": "2026-06-02T12:00:00Z"
}

Using an API key

Pass the key as a bearer token in the Authorization header on every request:

curl https://app.rensei.ai/api/public/sessions \
  -H "Authorization: Bearer rsk_live_abc123..."

Key types

Prop

Type

Scopes

Scopes constrain what an API key can access. They are stored as an array of strings on the api_keys.scopes column and enforced at the route handler level.

Scope	Access granted
`sessions:read`	Read session state, activities, and topology
`sessions:write`	Interact with sessions (prompt, stop)
`workflows:read`	Read workflow definitions and run history
`workflows:write`	Create and update workflows
`workers:register`	Register a daemon worker (worker registration keys only)
`org:read`	Read org members, projects, and settings
`org:write`	Modify org settings and members

Listing and revoking keys

# List all keys in an org
GET /api/org/{orgId}/keys
Authorization: Bearer rsk_live_<admin_key>

# Revoke a key
DELETE /api/org/{orgId}/keys/{keyId}
Authorization: Bearer rsk_live_<admin_key>

Worker registration key flow

Worker registration keys (keyType: worker_registration) have a specialized two-step flow:

Generate a registration key in Settings > API Keys. Keep this secret - it is equivalent to a credential.

Register the worker by passing the token to POST /v1/daemon/register (or POST /api/workers/register for AF-compatible daemons). The platform returns a short-lived runtimeJwt.

Use the runtime JWT as Authorization: Bearer <runtimeJwt> on all subsequent worker protocol calls. Refresh it before expiry via POST /api/workers/[id]/refresh-token.

See Worker Registration for the full flow and endpoint reference.

Security best practices

Rotate keys regularly. Use the revoke endpoint to delete old keys; create new ones on a schedule.
Scope minimally. Grant only the scopes your integration requires.
Never embed keys in client-side code. API keys are server-side secrets.
Prefer runtime JWTs for workers. Registration keys should be stored securely and used only once at daemon startup.

On this page