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) plus Search retrieval (search, pictures, pictures/similar, documents/list, documents/get, documents/similar): a leaked read-only token cannot generate text or change state, and it holds Read on every Search tenant whatever its grants say |
| Expiry | Never, or a date | Past it, the key no longer authenticates |
| Tool grants | Follow the server policy (default), none, or a named set, with an optional highest risk | Which server-executed tools the key may use, in chat, agents, workflows and on the MCP endpoint alike, and the highest risk any of them may carry (a narrower key for an experimental client, a wider one for a trusted assistant). 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 and at which level, Read, Write or Manage, over every collection or a chosen few (see the Access Model) |
| Approver | Off (default), or on | Whether the key may decide the pending approvals of its owner's agent runs through /lmkit/v1/approvals, so an application can host its own approval screen. Never the calls of a run the key started itself, unless self-approval is on (see Durable Agent Runs) |
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 whencluster_grantsis 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, add the
existing tenants it should reach (each with its level and collections), and the key leaves the
dialog working; the grants are written with the key in the same request, so a refused grant
mints no key. Through the API, tenant_grants on POST /lmkit/v1/admin/apikeys does the same.
A key minted without Search access (None chosen, or cluster_grants 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 |
6Quotas#
Quotas bound how much each caller may use: requests per minute and tokens per 24 hours (prompt plus completion, a rolling day). Three levels can state them, and every level that limits a caller applies; the tightest one binds:
| Level | Where it is set | Budget |
|---|---|---|
| Server quota | Access, Quotas | Each key gets the budget, or every caller shares one |
| Key group | Access, Quotas, a group | Each member key gets the budget, or the group shares one; a key belongs to one group at most |
| Key override | A key's Quota action | That key alone |
A request past a limit answers 429 with Retry-After and the rate-limit headers
OpenAI-compatible clients read (x-ratelimit-limit-requests, x-ratelimit-remaining-requests,
x-ratelimit-reset-requests and their -tokens counterparts); an admitted response carries the
same headers for its tightest limit. Past 80% of a limit, responses carry X-LMKit-Quota-Warning
and the operators get an alert. A caller reads its own standing at GET /lmkit/v1/usage/me,
which a quota never refuses.
- Requests are counted per clock minute, exactly, across every node of a farm.
- Tokens are charged when a request ends (a job, when it completes). A request starts while the budget is not spent and is never cut off mid-answer, so a long answer can finish past the limit; the next request is refused. Spend reaches the other nodes within seconds.
- Counters live in the identity store (the shared database on a farm), so a restart keeps the day's spend. A quota change applies to the next request, on every node.
7Stated 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.