API Keys

Rensei API keys (rsk_live_*) are the primary authentication mechanism for daemon workers, CI pipelines, and any service that needs programmatic access to the platform. Keys are scoped either to an entire organization or to one or more specific projects, and carry an explicit set of permission scopes.

Key format

Every key minted by the platform has the format:

rsk_live_<64 hex characters>

rsk_live_ is the fixed prefix (rsk = Rensei key, live = live environment). The 64-character suffix is 32 bytes of cryptographically random entropy (256 bits). Only the SHA-256 hash of the full key is stored - the plaintext is returned once at creation and never shown again.

Keys also have a 12-character display prefix (e.g. rsk_live_e4f2) that appears in the UI and audit logs so you can identify a key without exposing its secret.

Scopes

Every key declares one or more scopes from the following catalog:

Default scopes are applied automatically if you do not specify them:

• Project-scoped keys default to ["worker:register", "worker:poll", "worker:heartbeat", "worker:session"].
• Org-wide keys default to ["*"].

Project scoping

Keys are either org-wide or project-scoped:

// Org-wide - project_ids stored as null
projects: 'all'

// Project-scoped - project_ids = ['proj_abc123', 'proj_def456']
projects: ['proj_abc123', 'proj_def456']

A project-scoped key is only valid for the listed projects. An org-wide key (projects='all') has access to all projects in the org and is required for org_keys:write scope.

Creating a key

Via the UI

Navigate to Settings → API Keys → New Key. Choose a name, select project scope (or org-wide), optionally set an expiry, and click Create. Copy the key immediately - it will not be shown again.

Via the API

curl -X POST https://app.rensei.ai/api/org/api-keys \
  -H "Authorization: Bearer rsk_live_<your-org-wide-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "ci-worker-prod",
    "projects": ["proj_abc123"],
    "scopes": ["worker:register", "worker:poll", "worker:heartbeat", "worker:session"],
    "expiresAt": "2027-01-01T00:00:00Z"
  }'

Response (201):

{
  "id": "ak_3f9e2a1b4c5d",
  "orgId": "org_xxxxxxxxxxx",
  "name": "ci-worker-prod",
  "keyPrefix": "rsk_live_e4",
  "scopes": ["worker:register", "worker:poll", "worker:heartbeat", "worker:session"],
  "projectIds": ["proj_abc123"],
  "createdAt": "2026-06-02T14:00:00.000Z",
  "expiresAt": "2027-01-01T00:00:00.000Z",
  "fullKey": "rsk_live_e4f2a1b3c9d0..."
}

The fullKey field is only present in the creation response. Store it securely.

Using a key

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

curl https://app.rensei.ai/api/org/projects \
  -H "Authorization: Bearer rsk_live_<your-key>"

For daemon workers, the key is typically set via the RENSEI_WORKER_API_KEY environment variable and presented to the registration endpoint (worker:register scope) in exchange for a short-lived runtime JWT.

Expiry

Keys support an optional expiresAt timestamp. Expired keys are rejected at validation time. Keys without an expiry are valid until revoked. For long-lived CI/CD tokens, set a rotation reminder rather than relying on indefinite keys.

Revoking a key

Via the UI

Navigate to Settings → API Keys, find the key by its display prefix, and click Revoke.

Via the API

curl -X DELETE https://app.rensei.ai/api/org/api-keys/<key-id> \
  -H "Authorization: Bearer rsk_live_<your-org-wide-key>"

Revocation is immediate. Any in-flight requests using the revoked key will fail on the next validation. Revocation emits an api_key.revoked audit event.

Audit trail

Every key lifecycle event is recorded in the audit trail:

Audit events include the display prefix, scopes, and project IDs but never the key hash or plaintext.

Security best practices

• Rotate keys regularly. Use expiresAt to enforce rotation intervals for long-lived service keys.
• Use project-scoped keys for workers. Never give a daemon worker an org-wide * key unless it needs to manage other keys.
• Store keys in your secrets manager. Keys should live in Vault, AWS Secrets Manager, or equivalent - not in plain .env files committed to source control.
• Audit key usage. Review the audit trail periodically for unexpected api_key.created events, especially if you have org_keys:write delegation.

Related pages

• M2M Clients - OAuth client_credentials flow for service-to-service auth
• Members & RBAC - user-level access control
• Credentials - manage secrets that agents use at runtime
• Audit Trail - key events in the hash-chained log