# LIME

> Passport system for AI agents — one internet identity, Core-signed short-lived passports, local JWKS verify. Agents typically present the passport over MCP (Bearer). Sites can use the same identity for **site login** and **agent binding** (two different wires).

If you are an LLM or agent runtime: start at https://lime.pics/agent

LIME issues short-lived signed passports for Agents. Your Service verifies them locally via Core JWKS — 0 ms network to LIME on the verify hot path. Free forever for core agent identity. No human IdP required for agent/MCP wires. Python SDKs on PyPI.

## Choose a flow (IS → DO)

| Goal | Browser? | Flow id | Skill |
|------|----------|---------|-------|
| Call an MCP resource server | no | `mcp_oauth_token` | `lime-mcp-oauth` |
| Open a session on your site for an agent | yes — waiting screen on **your** site | `site_login` | `lime-site-login` |
| Link signed-in human ↔ agent_id | yes — Connect on lime.pics | `agent_binding` | `lime-agent-binding` |
| Verify AIT passport locally | no | `verify_passport` | `lime-verify-passport` |
| Verify inbound MCP Bearer on your RS | no | `verify_mcp_token` | `lime-verify-mcp` |

Decision skill: https://lime.pics/.well-known/agent-skills/lime-choose-flow/SKILL.md

**IS:** Site-login approve to LIME is an API call (Agent Token + PoW).  
**DO:** Obtain `login_request_id` from the waiting screen / site channel — never invent it.

**IS:** Binding delivery is `?binding_code=` then `POST /api/v1/modules/bindings/exchange`.  
**DO:** Exchange server-side with Site Token; verify `aud=lime-binding` via JWKS.  
**NEVER:** JWT in URL fragment or query as delivery.

## Read next (keep it short)

1. Platform skill → https://lime.pics/.well-known/agent-skills/lime-platform/SKILL.md
2. Choose-flow skill → https://lime.pics/.well-known/agent-skills/lime-choose-flow/SKILL.md
3. One flow skill from the matrix above
4. Python examples → https://lime.pics/.well-known/agent-context/examples/python.md  
   MCP→Postgres reference → https://lime.pics/.well-known/agent-context/examples/mcp-postgres.md

Fat package: https://lime.pics/.well-known/agent-context/  
Catalog: https://lime.pics/.well-known/agent-flows  
Auth: https://lime.pics/auth.md  
OpenAPI: https://lime.pics/.well-known/openapi/v1.json  
Product card: https://lime.pics/.well-known/agent-context/product.json  
Changelog: https://lime.pics/.well-known/agent-context/changelog.json

## Identity model

1. Owner account → `user_id`; agents belong to that owner.
2. Each Agent has stable public `agent_id` (`sub`) and long-lived **Agent Token** (`X-Agent-Token` / `LIME_AGENT_TOKEN`) — opaque auth to call LIME. The token does **not** issue passports. **Never send Agent Token to an MCP RS.**
3. Primary wire: Agent Token + `domain` → LIME returns RS256 JWT `aud=mcp` (~300s). Agent presents `Authorization: Bearer`. MCP RS verifies via JWKS and applies ACL itself.
4. **Site Token** (`X-Site-Token`) — opaque secret for website backends (create site-login / binding). Not a JWT. Never pasted into the agent. Not required for MCP RS verify.
5. **Site login ≠ agent binding** — use the matrix above; do not mix wires.
6. LIME attests identity. LIME is not a proxy, not an MCP host, and not your authorization engine.

## Compare (10 lines)

- Shared API key: long-lived secret on both sides → LIME: short-lived RS256 + local JWKS verify.
- Human OAuth/PKCE: browser Authorize click → LIME MCP wire: Agent Token → mint JWT (no human click).
- Human IdP bolted onto agents → LIME: agent passport + machine AS; not a full human IdP replacement.
- Your service owns ACL, tools, and session cookies; LIME owns attested `sub`.

## Canonical JWKS

**IS:** `https://lime.pics/api/v1/core/.well-known/jwks.json`  
**DO:** Fetch and cache that URL (follow 301 from `/.well-known/jwks.json` or `/key.json` if present).  
**NEVER:** Treat non-Core paths as a different key set.

## MCP + Postgres reference

**IS:** Guide `/docs/guides/mcp-server/` + open reference https://github.com/Mawyxx/lime-ref-postgres-mcp  
**DO:** Read `/.well-known/agent-context/examples/mcp-postgres.md` then the GitHub README.  
**NEVER:** Follow unpublished blog paths for this pattern.

## Anti-hallucination

- Auth model is **opaque Agent Token**, not agent client keypairs. `LimeAgent(agent_token=...)` loads `LIME_AGENT_TOKEN` only — it does **not** generate a key pair.
- Do not confuse `aud=mcp` with `aud=lime-site-login` / `aud=lime-binding`.
- Binding is human Connect only; Site Token stays on the site backend.
- `login_request_id` is UUID v4 on the wire (not `lr_…`).

## Do not invent

These paths are **not** LIME APIs (scanner bait → 404): `/fetch/`, `/proxy/`, `/load/`, `/url/`, `/api/exec`, `/.git/*`.

## Markdown pages

Request `Accept: text/markdown` on `/`, `/docs/`, `/docs/guides/`, `/blog/`, `/use-cases/`, `/mcp-oauth/` for Prefer-markdown negotiation.

Machine canon language: **English** (this file, `.well-known/*`, `auth.md`). Human UI may be EN/RU.