What it does
Each project has two keys. The anon key is publishable and carries the anon role. The service key is a secret for server-side use and carries admin power inside its project. The deployment also has a global API key for platform operations. Keys are random 256-bit values, and a rotation replaces both keys and the project signing secret together.
How it works
Creating a project generates an anon key and a service key, each 32 random bytes written as URL-safe text, and a 64-byte signing secret for the project's end-user tokens. The service key is returned once and the server keeps just its SHA-256 hash. A request presents a key in the apikey header or as a bearer token. The server tries the credential classes in a fixed order: a managed token, the global API key (compared in constant time), a project service key (matched by hash), a project anon key (matched exactly), a project end-user token, a platform token, and the optional global anon key.
A key resolves to a project and a role. The service key acts as admin inside its project and skips row-level policies. The anon key acts as the anon role and is subject to collection rules and policies. A project that is suspended, being deprovisioned or purged refuses its keys. A paused project accepts them for reads.
POST /admin/v1/projects/:id/keys/rotate replaces the anon key, the service key and the project signing secret in one write and returns the new keys, with the new service key shown once. The effect is immediate: the old keys and every end-user token signed under the old secret stop working. The route belongs to the platform plane, so it needs an organisation owner or admin, or a platform administrator.
The global API key is set with KYNETRA_API_KEY. It is a platform superuser credential that addresses every namespace. A server bound beyond loopback refuses to start with a global key shorter than 32 bytes.
Where you reach it
- HTTP
POST /admin/v1/orgs/:id/projects (returns anon_key and service_key) - HTTP
POST /admin/v1/projects/:id/keys/rotate - HTTP
apikey header or Authorization: Bearer <key> on every data route - Config
KYNETRA_API_KEY, KYNETRA_ANON_KEY
Example
# Needs a platform account that manages the project's organisation
curl -s -X POST "$KYNETRA_URL/admin/v1/projects/$PROJECT_ID/keys/rotate" \
-H "Authorization: Bearer $ACCESS_TOKEN"
# returns {"project": {...}, "anon_key": "...", "service_key": "...", "note": "..."}
# The old keys and all end-user tokens of the project stop working immediately.Limits
- A project has one anon key and one service key. Keys have no names, scopes or expiry dates, and rotation replaces them all at once. For scoped, expiring credentials see managed API tokens, which in this release administer tokens alone.
- Rotation has no overlap window. Rotate when every client can be updated at once.
- The service key is shown once and cannot be recovered. Rotate to obtain a new one.
- The global API key is a superuser credential. Keep it out of client code and browsers.
- Key creation and rotation are not recorded in the tamper-evident audit log in this release.
Evidence
- On this siteMulti-tenancy: keys, planes and lifecycle
- Tests13 project-credential tests in the auth routes (anon and service key resolution, suspended and purged projects, forged project claims) and tenancy tests for key isolation, cross-project token rejection and keys that stop working after a purge
Test coverage is listed as present in the engine repository at this edition. This page does not report test results.
KynetraDB is in private preview
Request a preview to try this against your own workload.