Business API for site backends and AI agent runtimes: site login, PoW-protected approve, JWT passports, and MCP OAuth federation (client_credentials for external resource servers). Owner portal, admin, and registration endpoints are not listed here — obtain site_token and agent_token once from the LIME user portal.
Base URL: https://lime.pics/api/v1
Scenario guides
LIME helps your site, agent, or MCP server recognize the other side without passing long-lived secrets around. Pick the thing you are building, then follow the matching guide.
GET/modules/agent-login/eventsWait for site login events (SSE)
SSE stream (text/event-stream). One SSE connection per site_id. Reconnect after each terminal event. On approved, the payload includes agent_passport_jwt for JWKS verification.
Header: X-Site-Token
Parameters
Name
Location
Type
Required
Description
X-Site-Token
Header
string
Yes
Site integrator secret from the LIME portal (prefix st_…). Scopes the SSE stream to this site.
Wire format: Content-Type text/event-stream. Each event is one data: line with JSON. Idle keepalive: {"type":"keepalive"}. Reconnect after each terminal event (approved or expired).
Site backend starts a PENDING login request. Requires X-Site-Token (issued once when the owner registers the site in the LIME portal). Body must be {}.
Header: X-Site-Token (site integrator secret)
Parameters
Name
Location
Type
Required
Description
X-Site-Token
Header
string
Yes
Site integrator secret from the LIME portal (prefix st_…). Issued once when the owner registers the site.
Site backend starts a PENDING binding request. Returns binding_id and connect_url. Prefer lime-sites-sdk create_binding_request (v2.0.0+). Portal GET /public and POST /complete are UI-only — do not call them from your site.
Header: X-Site-Token
Parameters
Name
Location
Type
Required
Description
X-Site-Token
Header
string
Yes
Site integrator secret from the LIME portal (prefix st_…).
redirect_uri
Body
string
Yes
Absolute http(s) callback URL on your site (any public host; private/metadata blocked). Production/staging require https. Portal complete redirects with #passport=<JWT> (fragment only).
GET/auth/requests/{request_id}Get login request for agent (SDK)
Agent worker: site gives you login_request_id → call this endpoint to read status, pow_challenge, pow_difficulty, expires_at, then run SDK login(request_id) or manual PoW + approve. No X-Site-Token, no X-Agent-Token.
Public (agent worker, no tokens)
Parameters
Name
Location
Type
Required
Description
request_id
Path
string
Yes
Login request ID from POST /modules/agent-login/requests → data.login_request_id. Site backend passes this to the agent worker.
GET/modules/oauth/.well-known/oauth-authorization-serverOAuth Authorization Server metadata
RFC 8414 discovery document (raw JSON). Full server-advertised field set at top level (RFC 8414 URLs, grant/response types, PKCE, LIME extensions). Public — no authentication. Same at GET /.well-known/oauth-authorization-server.
No authentication required. IP rate limit applies.
Issue an RS256 MCP access JWT for external resource servers. Send X-Agent-Token plus JSON body {"domain":"<hostname>"} (Content-Type: application/json). JWT includes claim domain; aud stays mcp. Response is raw RFC 6749 JSON (access_token, token_type, expires_in) with Cache-Control: no-store.
Header: X-Agent-Token (same opaque agent token as LIME APIs) plus JSON body domain. Valid agent token is sufficient for MCP JWT issuance.
Parameters
Name
Location
Type
Required
Description
X-Agent-Token
Header
string
Yes
Secret agent token from the LIME portal (prefix at_…). Same opaque LIME_AGENT_TOKEN used on other LIME APIs.
Anonymous read of any agent identity/trust snapshot plus presentation fields. After passport verification, call with claims.sub to render UI without X-Agent-Token.
No authentication required. Rate limit: 100 requests/minute per IP (429 RATE_LIMIT_EXCEEDED).
Parameters
Name
Location
Type
Required
Description
agent_id
Path
string
Yes
Agent UUID. Typically claims.sub from a verified passport or binding JWT.
Global public signing keys for verifying LIME agent passport JWTs (RS256). RFC 7517 raw JSON with top-level keys array. Cache by kid; refetch on signature failure.
Install lime-agents-sdk from PyPI (pypi.org/project/lime-agents-sdk) or GitHub (github.com/Mawyxx/lime-agents-sdk). LimeAgent.login() fetches the PoW challenge, solves it, and submits approve with retries.
Python API reference: lime-agents-sdk.readthedocs.io — login, MCP tools, and error types.
Requires LIME_AGENT_TOKEN in the agent process. Site backends still use X-Site-Token for create and events (out of SDK v1 scope).
API root (optional, default https://lime.pics/api/v1)
MCP OAuth (Authorization Server)
LIME exposes a machine-only OAuth 2.0 Authorization Server for MCP federation: external MCP resource servers accept RS256 JWTs issued here. This is not browser OAuth and not used for site login — site login stays on X-Site-Token / X-Agent-Token and passport JWTs.
Credentials: send your opaque agent_token as the X-Agent-Token header on POST /modules/oauth/token with JSON body {"domain":"<rs-hostname>"} (Content-Type: application/json). Missing domain is rejected (400). Any agent with a valid token may obtain an MCP access JWT bound to that domain.
Flow: discover metadata (RFC 8414 raw JSON; lime_token_request_body is json_domain) → POST token with X-Agent-Token + JSON domain → your MCP RS verifies the JWT with Core JWKS (RFC 7517 raw keys). Use lime-mcp-server-sdk ≥1.0.0 (mandatory expected_domain / LIME_EXPECTED_DOMAIN) for verification; lime-agents-sdk ≥1.0.0 Zero-Touch Auth (pass target=; SDK extracts domain and caches JWT per domain).
Metadata, token, and Core JWKS success responses are spec-native JSON (RFC 8414, RFC 6749, RFC 7517) — no LIME envelope.
MCP access JWTs are not accepted on LIME business APIs — sending one as X-Agent-Token returns 401 INVALID_AGENT_TOKEN. Use them only on your external MCP resource server.
JWT claims: sub is the agent UUID (no agent_id claim). Audience is mcp. Claim domain is the normalized RS hostname. Passport-specific claims (user_id, request_id) are never present in MCP tokens.
Verify MCP JWT on your resource server (lime-mcp-server-sdk)
from lime_mcp_server import TokenVerifierMCP_ACCESS_TOKEN="eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."# expected_domain = public hostname THIS server serves (no port).# Tokens minted for another hostname fail verification.verifier = TokenVerifier(expected_domain="your-mcp-rs.example")result = verifier.verify(MCP_ACCESS_TOKEN)if result.is_valid:print(result.agent_id, result.domain)
Variable
Description
LIME_AGENT_TOKEN
Agent secret — X-Agent-Token on /oauth/token with JSON domain (required)
LIME_API_BASE
API root (optional, default https://lime.pics/api/v1)
Python MCP Server SDK
Install lime-mcp-server-sdk ≥1.0.0 from PyPI (pypi.org/project/lime-mcp-server-sdk) or GitHub (github.com/Mawyxx/lime-mcp-server-sdk). TokenVerifier requires expected_domain (or LIME_EXPECTED_DOMAIN), fetches raw RFC 8414 metadata and Core JWKS (RFC 7517 top-level keys), and verifies RS256 MCP JWTs including claim domain match.
Python API reference: lime-mcp-server-sdk.readthedocs.io — installation, quickstart, and mkdocstrings API.
Agent identity is JWT claim sub (TokenValidationResult.agent_id is an alias); result.domain is the bound RS hostname. Framework adapters (e.g. FastMCP) belong in your RS or monorepo harness — not in the SDK wheel.
Architecture: ADR 0083 in the LIME monorepo docs (Zero-Touch RS domain binding 1.0.0).
Hostname this RS serves (required if not passed as expected_domain=; ports rejected)
LIME_BASE_URL
LIME issuer base URL (default https://lime.pics)
LIME_OAUTH_AUDIENCE
Expected JWT aud claim (default mcp)
LIME_JWKS_CACHE_TTL_SECONDS
JWKS cache TTL seconds (default 3600)
Python Site SDK
Install lime-sites-sdk ≥ 2.0.0 from PyPI (pypi.org/project/lime-sites-sdk) or GitHub (github.com/Mawyxx/lime-site-sdk). Construct LimeSite inside a running asyncio loop; on_login handlers receive SSE approved/expired events; create_login_request() starts Zero Human Auth.
Python API reference: lime-sites-sdk.readthedocs.io — FastAPI patterns, verify_passport, Binding helpers, and SSE notes.
Requires LIME_SITE_TOKEN on the site backend. Verify site-login passports with verify_passport(); Binding passports with verify_binding_passport(jwt) (crypto only — match claims["binding_id"] in your app).
import asynciofrom lime_sites import LimeSite# Backend only. LIME never sets your cookie — you do after verify_passport.# Browser: button → your API → waiting UI → your API sets the site session cookie.LIME_SITE_TOKEN="LIME_SITE_TOKEN_HERE"asyncdefmain() -> None: received = asyncio.Event() box: dict[str, object] = {} site = LimeSite(site_token=LIME_SITE_TOKEN)@site.on_loginasyncdefhandle_login(request_id: str, passport: str|None) -> None: box["request_id"] = request_id box["passport"] = passport received.set()# 1) Browser clicked "Sign in" → your backend creates the attempt req =await site.create_login_request()print("login_request_id:", req.request_id)# 2) YOU deliver req.request_id to the agent (your channel). LIME does not notify the agent.await asyncio.wait_for(received.wait(), timeout=120)if box.get("passport"): verified =await site.verify_passport(str(box["passport"]),expected_request_id=req.request_id, ) agent_id = verified.claims["agent_id"]# 3) Set YOUR site session cookie for agent_id — LIME does not create itprint("signed_in_agent_id:", agent_id)await site.aclose()asyncio.run(main())
Variable
Description
LIME_SITE_TOKEN
Site secret from user portal (required)
LIME_API_BASE
API root (optional, default https://lime.pics/api/v1)