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, with a working default#
A newly minted key can call the inference API and reach exactly the Search it was given:
- Search access. The create dialog preselects the default cluster, so a key minted with the
dialog's defaults searches on its first call: it provisions its own tenants in that cluster
and reaches only those, plus any tenant ticked at creation. None is one choice away for a key
that must never reach Search. Through the API (
POST /lmkit/v1/admin/apikeys) a key carries exactly the grants the request names, and none whenclusterGrantsis omitted. - No tenant reach beyond its own until granted per tenant.
- Tools follow the server policy the operator already curated.
The create dialog can wire a key completely in one pass: keep or change the cluster, tick the tenants it should also reach, and the key leaves the dialog working; the token reveal states the reach it left with.
A key minted without Search access (None chosen, or clusterGrants omitted through the API)
meets 400 This API key has no Search access on its first Search call, whatever the Search
section shows: the default cluster exists for the operator, not for a key that was never granted
it. The key's row in Access says Search access none, and the Requests page records the reason
beside the refused call; the row's Search access action grants the cluster, and the same call
goes through.
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 in the identity store (the shared database on a farm): the store holds no credential, and a key minted on one node authorizes on every node.
- 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.
- While the identity database is unreachable, keys already in a node's snapshot keep authorizing and a key not yet in it is refused with 401 until the database answers; nothing opens.
- Grants attach to the key id, so rotation never changes reach, and two keys never share reach by accident.