Lifetimes, codes and addresses

Lifetimes#

A passport's audience sets its purpose, who starts and receives it, its lifetime, and the claims it carries:

mcp is the default audience, and it is also the only scope the discovery document advertises (scopes_supported: ["mcp"]).

Request and helper lifetimes:

Lifetimes are upper bounds. Once LIME stops minting, the passports already issued expire on their own, so there is no call to LIME and no revocation list on the verify path.

Login-request statuses and their transitions:

approve returns APPROVED or DELIVERED. The happy path is PENDING → APPROVED → DELIVERING → DELIVERED; the timeout path is PENDING → EXPIRED.

Passport claims#

Every passport is an RS256 JWT signed by one Core key set; the aud claim selects the claim set:

Only the mcp audience derives iss from the issuer field of the OAuth AS metadata document (GET /api/v1/modules/oauth/.well-known/oauth-authorization-server); lime-site-login and lime-binding use a fixed Core issuer constant https://lime.pics, not the metadata. A verifier reads issuer from that metadata and requires the mcp passport iss to match it exactly (PyJWT exact match); the site SDK expects iss to equal the origin of its base_url. The mcp issuer default is environment-driven by LIME_OAUTH_ISSUER and must be set in production. The MCP verifier does not enforce the typ header value: it enforces iss, aud, sub, and the domain pin, and it validates iat within the leeway (alongside exp and nbf), so jti is not independently validated; client_id is still required, and the issuer always sets it equal to sub (RFC 9068). typ is a JOSE header (at+jwt), never a claim.

passport_version is "5" and appears only on lime-site-login and lime-binding; an mcp passport never carries it. domain is an mcp-only claim whose value is the normalized lowercase hostname. Read sub for the agent_id and treat jti as the unique passport id. An mcp passport that carries user_id, passport_version, or request_id is rejected (those claims are forbidden on the mcp audience).

Proof of work#

Approving a sign-in is gated by a proof of work (PoW), so the approve call cannot be replayed at will. The public read returns five fields:

Find a pow_nonce — a decimal string of 1–64 characters, ≥1 (the solver enumerates 1, 2, 3, …) — whose digest has the first pow_difficulty bits zero:

import hashlib

def solve(pow_challenge: str, difficulty: int) -> str:
    prefix = b"lime:pow:v1\0" + pow_challenge.encode() + b"\0"
    for n in range(1, 1 << 32):
        nonce = str(n)  # the nonce is sent verbatim, as this decimal text
        digest = hashlib.sha256(prefix + nonce.encode()).digest()
        if int.from_bytes(digest, "big") >> (256 - difficulty) == 0:
            return nonce
    raise RuntimeError("no nonce found")

The exact preimage is SHA-256( b"lime:pow:v1\0" || pow_challenge_as_received(UTF-8) || 0x00 || pow_nonce(UTF-8) ) and the first pow_difficulty bits of the digest must be zero; hash the challenge string exactly as received, never base64-decode it, and read both pow_challenge and pow_difficulty from the public read (GET /api/v1/auth/requests/{request_id}), not the create response.

Send it back as {"pow_nonce": "<POW_NONCE>"} on the approve call; a wrong or missing nonce returns INVALID_POW or MISSING_POW_NONCE (both 400).

Error codes#

Every code the public API returns, with the HTTP status it arrives with. Branch on the code, not on the message text.

Rows are grouped by flow: site-login and binding codes are returned to the site backend, verification and OAuth codes to the agent or the MCP server, and request codes to any client. NETWORK_ERROR, INVALID_RESPONSE and HTTP_ERROR are produced on the client and never cross the wire. This is the exact public integrator catalogue (59 codes); CAPTCHA, owner-session, registration and credential-rotation codes are portal-facing and deliberately not part of it, so they never cross the public wire. On POST /oauth/token a missing or wrong X-Agent-Token returns RFC invalid_client (401) — never the envelope codes MISSING_AGENT_TOKEN or INVALID_AGENT_TOKEN, which belong to other LIME endpoints.

Discovery#

The documents a client reads instead of hardcoding values:

Read token_endpoint and jwks_uri from the metadata rather than building URLs by hand. The AS metadata registration_endpoint, when advertised, currently returns 501 (not implemented), and /oauth/authorize returns 501 unsupported_response_type when the MCP-compatibility shim is off. These documents are raw top-level JSON, not the {"ok": true, "data": …} envelope of the application endpoints.

The published OpenAPI document declares info.version 1.0.0; the security-audit snapshot is 0.1.0 and is operator-facing. Only /api/v1 is served, and there is no deprecation or sunset mechanism — no other API version is published.

Keys#

The JWKS is one Core key set that verifies every audience — not per-service keys. It holds one active signing key plus, during a rotation, one optional rollover verification key that is simply published while it is configured. There is no active/rollover/retired state machine and no fixed rotation window: a verifier accepts the active key and the rollover key, and any other kid is rejected.

• Canonical URL: https://lime.pics/api/v1/core/.well-known/jwks.json.
• Serve it with Cache-Control: public, max-age=60, must-revalidate. Each JWK has exactly kty=RSA, use=sig, alg=RS256, plus kid, n, e with e=AQAB; the set publishes the active key plus optionally one rollover key — 1–2 keys — unique and sorted by kid (the validator applies an internal hard cap of 8 keys, not an expected count). On an unknown kid the verifier refetches, but the forced refetch is rate-limited by LIME_JWKS_MIN_REFRESH_SECONDS (default 60), so "immediately, ignoring the cache TTL" holds only outside that window; the site SDK does force-refetch.
• RS256 only: reject any other alg, never accept none or a symmetric algorithm.
• Clock skew: the MCP verifier uses one leeway, LIME_JWT_VERIFY_LEEWAY_SECONDS (default 120), applied to exp, iat and nbf; the site SDK applies its 30-second leeway to nbf only — exp has zero leeway; the LIME Core internal verifier is strict on exp and nbf (no leeway) and tolerates iat up to 300 s ahead of now.
• Read iss from the issuer field of the OAuth AS metadata (GET /api/v1/modules/oauth/.well-known/oauth-authorization-server) and match it exactly — never hardcode it.
• expected_domain matching normalizes both sides (lowercase; strip scheme/path; reject userinfo, IP literal, reserved host, and any port) and requires exact equality with the passport domain claim — not a suffix or subdomain match. A port is rejected, not stripped.
• domain normalization: reject a non-string or empty value; strip a leading https:// or http://; cut at the first /; lowercase; reject @ (userinfo) and bracket/IP literals (any :, IPv4 or IPv6); enforce a DNS-hostname shape. Reserved hosts are rejected: localhost, metadata.google.internal, metadata, kubernetes, kubernetes.default, kubernetes.default.svc, and any name ending in .localhost, .local, .internal, .intranet, .corp, .home, or .lan.

Limits#

Rate limits use a Redis sliding window; the default window is 60 s. A denied request does not consume quota, so only allowed requests fill the window. When Retry-After is present it is an integer number of seconds equal to the whole window: it is sent on the generic per-IP / per-user 429, on ACCOUNT_TEMPORARILY_LOCKED, ROTATION_COOLDOWN_ACTIVE and JOURNAL_EXPORT_RATE_LIMITED (portal-facing), and on 503 CAPTCHA_UNAVAILABLE (value 5); it is absent on the OAuth 429, the portal-visit 429, the data-rights 429 and 503 RATE_LIMIT_UNAVAILABLE. Do not treat it as universal — on any 429, back off exponentially with jitter and cap retries.

Request and field bounds:

Do not call LIME on every verify request: the signature is checked locally via JWKS. The mcp audience means "mint a short-lived JWT for an external MCP server", not "present Bearer to the LIME APIs" — those need the opaque Agent Token or Site Token.

Public SDK surface#

Official Python packages wrap the calls above, so you rarely call the HTTP API by hand.

Constructors are keyword-only. Pass the secret explicitly (agent_token= / site_token=) or let the client read the documented environment variable when the argument is omitted:

The agent and site clients take the API root including `/api/v1` (LIME_API_BASE); the verifier takes the origin only (LIME_BASE_URL). TokenVerifier.expected_domain is required — a missing pin raises ValueError.

Method signatures:

get_mcp_access_token takes a DNS target, not a domain; a non-DNS target raises ValueError. verify is synchronous and never raises on a bad token; verify_async runs it in a worker thread. warmup returns False and logs on failure unless raise_on_failure=True; refresh_cache force-refetches and is rate-limited by LIME_JWKS_MIN_REFRESH_SECONDS.

Returned values and failures:

TokenValidationResult carries is_valid: bool, claims (dict | None) and error (str | None); .agent_id is claims["sub"] when valid, .domain is the domain claim, and .valid_claims returns the claims only when valid. Datetime wire fields (expires_at, created_at, approved_at, delivered_at) are ISO-8601 UTC with a +00:00 offset (no Z), and null when unset.

Exceptions carry .message, .code, .http_status and .detail (base LimeError(message, *, code, http_status, detail); ApiError(code, message, *, http_status, detail)). The agent hierarchy is LimeError → AuthenticationError (AgentInactiveError, AgentUserSuspendedError), PowTimeoutError, RateLimitError, ApiError (OAuthCapabilityError, AuthUnavailableError), McpAuthenticationError. The site hierarchy is LimeError → AuthenticationError, RequestExpiredError (defined; expiry is delivered as on_login(..., passport=None) instead), InvalidPassportError, RateLimitError, ApiError (SiteAuthUnavailableError). RateLimitError has no retry_after attribute, and the Retry-After header is not captured.

• Install: pip install lime-agents-sdk lime-mcp-server-sdk lime-sites-sdk (see each package for the full reference and version floors).
• The agent client caches the passport per domain, re-mints 30 s before expiry, and re-mints once on a 401 from a service; the verifier and site client cache JWKS and refresh on an unknown kid (LIME_JWKS_CACHE_TTL_SECONDS: 3600 in the verifier, 300 in the site client).
• verify_passport raises InvalidPassportError instead of returning valid=false — wrap it; the request_id mismatch message is JWT request_id claim does not match expected request.
• The site SDK accepts a login passport with a TTL up to 120 seconds (_LOGIN_MAX_TTL_SECONDS); the default expiry is still 60 seconds.

Portal operations#

Creating an agent or a site and minting or rotating their Agent Token / Site Token are portal-only (the LIME portal browser UI) — no public API mints an Agent Token or a Site Token. The portal shows each secret exactly once; store it, then use it as X-Agent-Token / X-Site-Token. There is no public sandbox or staging host for the LIME API: https://lime.pics is the only public origin of the LIME API/issuer, and any staging tier is operator-only; the public demo MCP resource server at https://demo.lime.pics/mcp is a separate host, not the LIME API origin.

Next steps#

• API catalogue: methods and credentials
• FAQ: answers about the model