# LIME auth.md

Machine-oriented authentication guide for integrators and agents.  
Primary scenario discovery: `https://lime.pics/.well-known/agent-flows`.

## What LIME is

LIME is a **passport system** for AI agents: one internet identity under an owner account, Core-signed short-lived passport JWTs, local JWKS verify. Agents typically present the passport over **MCP** (`Authorization: Bearer`, `aud=mcp`). The same identity also supports site login and agent binding.

LIME issues opaque site and agent credentials and acts as a machine-only OAuth Authorization Server that mints **outbound** MCP access JWTs for **external** MCP resource servers.

LIME is **not** an MCP server. It does not host MCP tools or publish an MCP Server Card. LIME attests identity — your service decides ACL.

## Credentials (wire)

| Actor | Credential | Wire | Needed for MCP RS? |
|-------|------------|------|--------------------|
| Owner (portal browser) | Session cookie | `lime_session` (+ CSRF) | No |
| Agent runtime | **Agent Token** | `X-Agent-Token` / env `LIME_AGENT_TOKEN` | **Yes — to call LIME only** (never sent to the MCP RS; token does not issue passports) |
| Site integrator backend | **Site Token** | `X-Site-Token` | **No** — only site login + binding |
| External MCP resource server | MCP OAuth JWT | `Authorization: Bearer` on the **MCP RS only** | Verify only (JWKS) |

**Agent Token** is the long-lived opaque secret the agent uses to authenticate to LIME (Telegram-bot-token analogy). It does **not** issue or carry a passport. The agent calls LIME with `X-Agent-Token` (+ `domain`); **LIME** returns a short-lived Core-signed passport JWT. Services see that JWT, never the Agent Token.

**Site Token** is required only when a website backend creates site-login or binding requests. An MCP resource server does **not** register or use a Site Token — JWKS + `TokenVerifier` is enough.

Never send `LIME_AGENT_TOKEN` / `X-Agent-Token` to an MCP resource server.  
Never present an MCP JWT (`aud=mcp`) as authentication to LIME `/api/v1/**` APIs.  
Do not invent agent client-auth keypairs for mTLS-style registration — Core signs RS256.

## How credentials are provisioned

Supported registration method: **human owner portal** (Auth.md `identity_assertion` + `verified_email` → owner registers/logs in, then mints opaque tokens).

1. Owner registers and logs in at `https://lime.pics/register/` / `https://lime.pics/login/` (`register_uri` / `claim_uri` / `identity_endpoint` / `claim_endpoint` in AS `agent_auth`).
2. With an owner session, create an agent (`POST /api/v1/core/agents/register`) and/or a site (`POST /api/v1/foundation/sites/register`).
3. Store the opaque token server-side on the agent runtime or site backend (shown once).
4. Agent runtime authenticates to LIME APIs with `X-Agent-Token`; site backends use `X-Site-Token` (site flows only).

There is no anonymous public self-mint of agent tokens and no live WorkOS `POST /agent/identity` IdP / ID-JAG self-registration for Core agent auth.

## Primary wire — passport over MCP transport

1. Discover AS metadata: `GET /.well-known/oauth-authorization-server` (or `/api/v1/modules/oauth/.well-known/oauth-authorization-server`).
2. Agent → LIME: `POST /api/v1/modules/oauth/token` with `X-Agent-Token` and JSON `{"domain":"<hostname>"}`. **LIME** issues RS256 JWT `aud=mcp`, TTL ~300s, claims include `sub` (= `agent_id`) and `domain`.
3. Agent calls the MCP RS with `Authorization: Bearer <jwt>`.
4. RS verifies locally via Core JWKS (`TokenVerifier(expected_domain=...)`) — 0 ms network to LIME on the verify hot path — then applies **your** ACL.

Guides: `/docs/guides/agent-mcp/`, `/docs/guides/mcp-server/`.

How-to (Postgres reference): `/blog/secure-mcp-server-ai-agents-postgres/` — Agent Token → LIME mints JWT → TokenVerifier → whitelist/capabilities.

## Also — Zero Human Auth (site login)

Headless path: site creates a login request with **Site Token** → agent receives `login_request_id` out-of-band → agent PoW approve with **Agent Token** → site receives AIT passport (`aud=lime-site-login`) over SSE and verifies via Core JWKS.

See flow `site_login` in `/.well-known/agent-flows` and guide `/docs/guides/site-login/`.

## Also — Agent binding

Site creates a binding request with **Site Token**; owner completes Connect; site verifies binding passport (`aud=lime-binding`) and stores `agent_id` locally. LIME does not store the site’s internal user mapping.

## OAuth AS + protected resource

- Authorization Server metadata: `https://lime.pics/.well-known/oauth-authorization-server`
- Protected resource metadata (RFC 9728): `https://lime.pics/.well-known/oauth-protected-resource`  
  (`resource=https://lime.pics/api/v1`, `authorization_servers=["https://lime.pics"]`, `scopes_supported=["mcp"]`)
- Core JWKS: `https://lime.pics/api/v1/core/.well-known/jwks.json`

Scope `mcp` means: mint a short-lived JWT for calling an **external** MCP RS. It does **not** mean Bearer MCP JWT unlocks LIME HTTP APIs (those use opaque `X-Agent-Token` / `X-Site-Token`).

## Standards inventory (optional)

RFC 9727 API catalog: `https://lime.pics/.well-known/api-catalog`  
Curated OpenAPI: `https://lime.pics/.well-known/openapi/v1.json`

## Non-goals

- Browser “Sign in with …” IdP for agent/site API auth
- Using MCP JWT against LIME Core/module APIs
- Publishing MCP Server Card / A2A Agent Card / WebMCP on lime.pics
- Being a generic MCP-only auth vendor — LIME is a passport system for agents; MCP is the primary presentation transport today