API Keys
API endpoints for managing API keys for programmatic access.
Overview
API keys provide an alternative authentication method for programmatic and service-to-service access to the Reten platform. Instead of using JWT tokens obtained through the login flow, clients can authenticate by sending an API key in the x-api-key header.
API keys belong to a specific user and tenant, and carry an explicit set of permissions chosen by their owner — always a subset of the permissions the owner currently holds. The owner can replace that set at any time with PUT /api/api-keys/:id/permissions without rotating the secret, and on every request the key's effective permissions are the intersection of its stored set with the owner's current permissions. Keys are stored as SHA-256 hashes — the plaintext key is only shown once at creation time.
Each key also has a scope, chosen when it is created: a project key always works in one project, and a tenant key serves every project of the tenant and sends x-project-id where the endpoint requires it or to narrow a request to one project. See Key scope.
Key properties
| Property | Description |
|---|---|
name | Human-readable label for identifying the key |
keyPrefix | Display prefix (e.g., rtn_sk_a1b2c3d4) for identification without exposing the full key |
permissions | Explicit list of permissions granted to this key |
projectId | The key's project (string, a UUID), or null for a tenant key |
expiresAt | Optional expiration date after which the key is rejected |
lastUsedAt | Timestamp of the last successful authentication with this key |
Authentication with API keys
curl -X GET https://api.reten.ai/api/commerces \
-H "x-api-key: rtn_sk_a1b2c3d4e5f6..." \
-H "Content-Type: application/json"When using an API key, the x-tenant-id header is not required — the tenant is resolved automatically from the key's associated tenant. On project-scoped endpoints, a tenant key also sends the x-project-id header; on project-optional endpoints the header is optional. A project key always works in its own project — see Key scope.