Keys and Authentication
How callers prove who they are and what each credential can do. The short version: every API call carries a bearer token; a key's reach is the sum of narrow, explicit grants; everything ambiguous fails closed.
1The credential#
API keys are minted in the admin panel's Access section and presented on every call as:
Authorization: Bearer lmk_...
The raw token is shown ONCE, at creation. The server stores only a hash, so the token cannot be recovered later, only replaced: Regenerate issues a new token under the same key identity, and the old token stops working immediately. Because resources belong to the key's identity, not its token, a regenerated key keeps access to everything it had.
Whether a key is REQUIRED depends on the network posture: a loopback-only server may accept keyless calls while the anonymous toggle is on; a network-reachable server refuses them always (see Going Live).
2What a key carries#
Each key holds independent, individually editable controls:
| Control | Values | What it bounds |
|---|---|---|
| Scope | Full, or Read-only | Read-only keys are confined to safe HTTP methods (GET, HEAD, OPTIONS): a leaked read-only token cannot trigger inference or change state |
| Expiry | Never, or a date | Past it, the key no longer authenticates |
| Tool grants | Follow the server policy (default), none, or a named set | Which server-executed tools the key may use in chat. A grant can only NARROW the server's Tools policy, never widen it (see Tools and Egress) |
| Search access | None (the minting default), all clusters, or named clusters | Which search clusters the key may address at all; inside them, per-tenant grants decide what it reaches (see the Access Model) |
The keys list states only what deviates from the defaults, so an unusual key is visible at a glance and an ordinary one reads quietly.
3Least privilege by default#
A newly minted key can call the inference API, and nothing more that is grantable:
- No search access until a cluster is chosen at creation or granted later.
- No tenant reach until granted per tenant.
- Tools follow the server policy the operator already curated.
The create dialog can wire a key completely in one pass: pick a cluster, tick the tenants it should reach, and the key leaves the dialog working.
4SSO and provider tokens#
When OIDC sign-on is configured, the API also accepts provider-issued JWTs as bearer tokens. They authenticate and are attributed to their owner, and they can be marked read-only, but they are not store keys: they hold no tenant or cluster grants, so they reach no Search data. Search callers use minted keys. Wiring both halves, admin sign-in and API tokens, is Single Sign-On.
5Lifecycle#
| Action | Effect |
|---|---|
| Revoke | The key stops authenticating on the next request; history is kept; Restore re-enables it |
| Regenerate | New token, same identity: access and history persist, the old token dies immediately |
| Delete | The key and its ability to authenticate are permanently removed; prefer Revoke when an audit trail matters |
| Expire | Automatic revocation at the chosen instant |
6Stated plainly#
- The token is secret, shown once, and stored only as a hash: the key file on disk is not a credential.
- Every control narrows; nothing a key carries can exceed what the server policy allows.
- Unknown, revoked, and expired keys fail closed everywhere, including mid-flight.
- Grants attach to the key id, so rotation never changes reach, and two keys never share reach by accident.