Reference
Concepts: passports and security
LIME's identity model in one place: a permanent subject and a short-lived passport, the three audiences, two kinds of long-lived credentials, local JWKS verification, and the boundary of responsibility. For AI agents: /docs/all.en.md.
Subject and proof#
An agent is a long-lived subject with a permanent agent_id: a UUID that does not change for the life of the agent. The name and avatar can change; the identifier cannot. Proof is separated from the subject: a passport confirms the agent_id to one particular service and lives for a fixed lifetime set by its audience (lifetimes). Because of that split, losing a passport is not the same as losing the identity — the agent simply mints a new one. The chain is short: an agent calls LIME, Core mints a passport, and your service verifies it locally.
Passport and audiences#
A passport is an RS256 JWT that Core issues for a permanent agent_id; its aud claim names the purpose — mcp, lime-site-login, or lime-binding — and a service accepts only its own audience. Lifetimes are in the value reference and the claim sets in the claims reference.
Credentials#
| Credential | Stored by | Sent to | Header | Lifetime |
|---|---|---|---|---|
| Agent Token | Agent runtime .env (LIME_AGENT_TOKEN) | LIME only | X-Agent-Token | Long-lived until rotated |
| Site Token | Site backend (LIME_SITE_TOKEN) | LIME only | X-Site-Token | Long-lived until rotated |
| Passport | Not stored; minted per call | The service | Authorization: Bearer <PASSPORT> | ~300 s for mcp and ~60 s for site login and binding (lifetimes) |
Local verification#
A service downloads the public keys from GET /api/v1/core/.well-known/jwks.json, caches them, and verifies the passport itself. Only RS256 and the enforced claims are checked: iss (issuer), aud (audience), and exp (expiry) with a configurable clock-skew tolerance, plus sub (subject) and a domain that must match the service's own host (domain pin). The key is selected by the kid in the header, and on an unknown kid the cache is refreshed rather than trusting an old signature.
The JWKS holds one active signing key plus, during a rotation, one optional rollover verification key that is published while it is configured. There is no state machine and no fixed rotation window: the verifier accepts the active key and the rollover key, and any other kid is rejected. There are no calls to LIME on the verify path and no local revocation list — revocation is bounded by the passport's short lifetime.
Binding#
Binding is proof of ownership: a service checks that the agent behind an agent_id belongs to its user, then stores the resulting agent_id ↔ user_id link itself — LIME keeps no internal site mapping and does not revoke it. The one-time code travels in the URL, but a JWT never does. The full flow is on Linking a user to an agent.
Boundary#
LIME attests an agent's identity and leaves authorization to the service. It does not host an MCP server or expose tools of its own. It does not sign people in and is not a human identity provider. It does not proxy traffic or sit on the request path. It does not decide access rights. Everything that is not "who this is" belongs to your service.