What it does
Organisation-owned bearer tokens that carry a capability list rather than a role. They are created, rotated, disabled and revoked over HTTP, can expire, and are stored as SHA-256 hashes and in no other form. The capability set is closed and in this release covers token administration alone.
How it works
POST /admin/tokens creates a token for an organisation with a name, an optional RFC 3339 expiry and a capability list drawn from tokens_read and tokens_manage. The response returns the token once: kdb_ followed by 40 hex characters, which is 160 random bits. The server stores the SHA-256 hash, the organisation, the issuer, the capabilities, the expiry and a version number. A listing never returns the hash.
A credential that starts with kdb_ is treated as a managed token and as nothing else. If it is unknown, expired, disabled, revoked or rotated away, the request is refused outright and is never retried as a global key, project key or user token. A managed token has no role, so role-gated and data routes reject it. It can call the token routes, within its own organisation.
Rotation names the version the caller last saw, so two concurrent rotations have exactly one winner and the old token stops working at once. Disable suspends a token and enable restores it, and revoke ends it. A managed token with tokens_manage can create child tokens with a subset of its own capabilities, never more. Deleting an organisation removes the tokens bound to it. Each lifecycle action is written to the audit log under a stable actor name that never includes the token.
Authorisation is checked on every request. A platform administrator or the global API key can manage tokens for any organisation, and a managed token can act on its own organisation and no other. Creation fails for an organisation that does not exist, for an unknown capability name, and for a body that names a role, because the body format is strict. An expired or disabled token is refused at its next request.
Where you reach it
- HTTP
GET /admin/tokens, POST /admin/tokens - HTTP
DELETE /admin/tokens/:id - HTTP
POST /admin/tokens/:id/rotate, POST /admin/tokens/:id/disable, POST /admin/tokens/:id/enable
Example
curl -s -X POST "$KYNETRA_URL/admin/tokens" \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{"name":"token-audit","owner_org_id":"<organisation id>","capabilities":["tokens_read"]}'
# returns {"token": "kdb_...", "record": {...}}; the token is shown onceLimits
- The capability set is closed: tokens_read and tokens_manage. These tokens do not grant read or write access to data, projects or any other route. They administer tokens.
- A token is shown once, at creation and at rotation. It cannot be recovered afterwards.
- Tokens belong to an organisation and are never bound to a project.
Evidence
- On this siteSecurity overview
- Tests31 token tests (hash never serialised, access limited to the granted capabilities, cross-organisation refusal, delegation without amplification, expiry, disable and revoke, rotation with one winner, survival across restart)
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.