Site login

Site backend · header X-Site-Token

Agent

Agent worker · fetch PoW (public) · approve with X-Agent-Token

OAuth for MCP

Machine-only Authorization Server · client_credentials · JWT for external MCP RS

Core / Public keys

Verify passport JWTs · public JWKS · agent profiles · no auth

Site login

Site backend · header X-Site-Token

Agent

Agent worker · fetch PoW (public) · approve with X-Agent-Token

OAuth for MCP

Machine-only Authorization Server · client_credentials · JWT for external MCP RS

Core / Public keys

Verify passport JWTs · public JWKS · agent profiles · no auth

Documentation

Integration API

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

New to LIME? Pick the scenario that matches your role. Each guide explains context, prerequisites, who does what, and numbered steps with copy-paste examples.

Zero Human Auth (site)

Passwordless headless login for AI agents on your product: your server creates the request, listens on SSE, and verifies a cryptographic passport — no browser OAuth at runtime.

Agent Binding (site)

Two-click linking: your user connects their LIME agent to a local account via browser redirect — your backend only creates the request and verifies the callback passport.

MCP server (passport verification)

Secure your MCP tools: verify LIME JWTs locally with JWKS, trust claims.sub as agent_id — no calls back to LIME per request.

Agent programmatic access (MCP)

Teach your bot to fetch MCP JWTs from LIME and call federated tools with Bearer — machine-only, no browser.

Agent programmatic access (Zero Human Auth)

Your bot approves a site login headlessly: fetch PoW, solve it, call approve — no browser, no site_token, no SSE on your side.

Open all guides →

Endpoints

Site login

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

Name	Location	Type	Required
X-Site-Token	header	string	No

Example request

curl
  -sS
  -N
  -X GET
  -H "Accept: application/json"
  -H "X-Site-Token: {your_site_token}"
  "https://lime.pics/api/v1/modules/agent-login/events"

Parameters

Name	Where	How to get	Example
`X-Site-Token`	Header	Owner portal → register site → copy site_token once (header X-Site-Token, prefix st_…).	`st_site_main_…`

Example SSE data payload

{
  "type": "approved",
  "login_request_id": "lr_flow_demo",
  "status": "approved",
  "agent_passport_jwt": "eyJhbG..."
}

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).

POST/modules/agent-login/requestsCreate login request

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)

Name	Location	Type	Required
X-Site-Token	header	string	No

Example request

curl
  -sS
  -X POST
  -H "Accept: application/json"
  -H "X-Site-Token: {your_site_token}"
  "https://lime.pics/api/v1/modules/agent-login/requests"
  -H "Content-Type: application/json"
  -d '{}'

Parameters

Name	Where	How to get	Example
`X-Site-Token`	Header	Owner portal → register site → copy site_token once (header X-Site-Token, prefix st_…).	`st_site_main_…`

Example response

{
  "ok": true,
  "data": {
    "login_request_id": "lr_flow_demo",
    "status": "PENDING",
    "expires_at": "2026-06-02T12:02:00Z"
  }
}

GET/modules/agent-login/requests/{request_id}Get login request status

Poll request status from your backend. Caller site_id must match the row (via X-Site-Token). Returns status only — no JWT in the body.

Header: X-Site-Token

Name	Location	Type	Required
request_id	path	string	Yes
X-Site-Token	header	string	No

Example request

curl
  -sS
  -X GET
  -H "Accept: application/json"
  -H "X-Site-Token: {your_site_token}"
  "https://lime.pics/api/v1/modules/agent-login/requests/{request_id}"

Parameters

Name	Where	How to get	Example
`request_id`	Path	Response of POST /modules/agent-login/requests → data.login_request_id.	`lr_flow_demo`
`X-Site-Token`	Header	Owner portal → register site → copy site_token once (header X-Site-Token, prefix st_…).	`st_site_main_…`

Example response

{
  "ok": true,
  "data": {
    "login_request_id": "lr_flow_demo",
    "status": "PENDING",
    "expires_at": "2026-06-02T12:02:00Z"
  }
}

POST/modules/bindings/requestsCreate agent binding request

Site backend starts a PENDING binding request. Returns binding_id and connect_url. See Integration guide → Agent Binding (HTTP). Portal GET /public and POST /complete are UI-only — do not call them from your site.

Header: X-Site-Token

Name	Location	Type	Required
X-Site-Token	header	string	No

Example request

curl
  -sS
  -X POST
  -H "Accept: application/json"
  -H "X-Site-Token: {your_site_token}"
  "https://lime.pics/api/v1/modules/bindings/requests"
  -H "Content-Type: application/json"
  -d '{"redirect_uri":"https://mysite.example/binding-callback"}'

Example response

{
  "ok": true,
  "data": {
    "binding_id": "bnd_a1b2c3d4e5f6",
    "connect_url": "https://lime.pics/connect/?binding_id=bnd_a1b2c3d4e5f6",
    "status": "PENDING",
    "expires_at": "2026-07-16T12:10:00Z"
  }
}

Agent

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)

Name	Location	Type	Required
request_id	path	string	Yes

Example request

curl
  -sS
  -X GET
  -H "Accept: application/json"
  "https://lime.pics/api/v1/auth/requests/{request_id}"

Parameters

Name	Where	How to get	Example
`request_id`	Path	Site backend passes login_request_id to your agent worker (from the create response).	`lr_flow_demo`

Example response

{
  "ok": true,
  "data": {
    "request_id": "lr_flow_demo",
    "status": "PENDING",
    "pow_challenge": "xK9mP2nQ7vR4sT1uW8yZ0aB3cD6eF",
    "pow_difficulty": 15,
    "expires_at": "2026-06-02T12:02:00Z"
  }
}

GET/core/agents/me/profileGet agent profile

Authenticated agent read (X-Agent-Token). For site UI after login without agent token, use GET /agents/{agent_id}.

Header: X-Agent-Token

Name	Location	Type	Required
X-Agent-Token	header	string	No
Authorization	header	string	No

Example request

curl
  -sS
  -X GET
  -H "Accept: application/json"
  -H "X-Agent-Token: {your_agent_token}"
  -H "Authorization: {your_authorization}"
  "https://lime.pics/api/v1/core/agents/me/profile"

Parameters

Name	Where	How to get	Example
`X-Agent-Token`	Header	Owner portal → create agent → copy agent_token once (header X-Agent-Token, prefix at_…).	`at_ag_alpha_…`

Example response

{
  "ok": true,
  "data": {
    "agent_id": "agt_ag_alpha",
    "user_id": "own_main",
    "user_kyc_level": 2,
    "agent_reputation": 5,
    "display_name": "My Agent",
    "avatar_url": null,
    "description": null
  }
}

POST/modules/agent-login/requests/{request_id}/approveApprove login request

Agent runtime confirms the login. Requires X-Agent-Token, site_login:approve, and body with pow_nonce. Missing/invalid PoW → 400 MISSING_POW_NONCE / INVALID_POW. Duplicate approve → 409 SITE_LOGIN_CONFLICT.

Header: X-Agent-Token (agent secret)

Name	Location	Type	Required
request_id	path	string	Yes
X-Agent-Token	header	string	No
Authorization	header	string	No

Example request

curl
  -sS
  -X POST
  -H "Accept: application/json"
  -H "X-Agent-Token: {your_agent_token}"
  -H "Authorization: {your_authorization}"
  "https://lime.pics/api/v1/modules/agent-login/requests/{request_id}/approve"
  -H "Content-Type: application/json"
  -d '{"pow_nonce":"12345678"}'

Parameters

Name	Where	How to get	Example
`request_id`	Path	Response of POST /modules/agent-login/requests → data.login_request_id.	`lr_flow_demo`
`X-Agent-Token`	Header	Owner portal → create agent → copy agent_token once (header X-Agent-Token, prefix at_…).	`at_ag_alpha_…`
`pow_nonce`	Body	Proof-of-Work solution: nonce where SHA-256(challenge+nonce) < 2^(256−difficulty). Challenge from GET /auth/requests/{id} (canonical SDK endpoint). Same-agent delivery retry on APPROVED skips PoW verification.	`12345678`

Example response

{
  "ok": true,
  "data": {
    "request_id": "lr_flow_demo",
    "site_id": "site_main",
    "status": "DELIVERED",
    "expires_at": "2026-06-02T12:02:00Z",
    "approved_agent_id": "agt_ag_alpha"
  }
}

OAuth for MCP

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.

Example request

curl
  -sS
  -X GET
  -H "Accept: application/json"
  "https://lime.pics/api/v1/modules/oauth/.well-known/oauth-authorization-server"

Example response

{
  "issuer": "https://lime.pics",
  "authorization_endpoint": "https://lime.pics/api/v1/modules/oauth/authorize",
  "token_endpoint": "https://lime.pics/api/v1/modules/oauth/token",
  "jwks_uri": "https://lime.pics/api/v1/core/.well-known/jwks.json",
  "registration_endpoint": "https://lime.pics/api/v1/modules/oauth/register",
  "grant_types_supported": [
    "authorization_code",
    "client_credentials"
  ],
  "response_types_supported": [
    "code"
  ],
  "scopes_supported": [
    "mcp"
  ],
  "token_endpoint_auth_methods_supported": [
    "none"
  ],
  "code_challenge_methods_supported": [
    "S256"
  ],
  "lime_agent_token_header": "X-Agent-Token",
  "lime_token_request_body": "grant_type",
  "lime_default_audience": "mcp"
}

POST/modules/oauth/tokenOAuth token (client_credentials)

Issue an RS256 MCP access JWT for external resource servers. Send X-Agent-Token header only (empty body). 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). Valid agent token is sufficient for MCP JWT issuance.

Name	Location	Type	Required
X-Agent-Token	header	string	Yes

Example request

curl
  -sS
  -X POST
  -H "Accept: application/json"
  -H "X-Agent-Token: {your_agent_token}"
  "https://lime.pics/api/v1/modules/oauth/token"

Parameters

Name	Where	How to get	Example
`X-Agent-Token`	Header	Same opaque secret as LIME APIs (LIME_AGENT_TOKEN). Sent as X-Agent-Token header on POST /modules/oauth/token.	`at_ag_alpha_…`

Example response

{
  "access_token": "eyJhbG...",
  "token_type": "Bearer",
  "expires_in": 3600
}

Core / Public keys

GET/agents/{agent_id}Get public agent profile

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).

Name	Location	Type	Required
agent_id	path	string	Yes

Example request

curl
  -sS
  -X GET
  -H "Accept: application/json"
  "https://lime.pics/api/v1/agents/{agent_id}"

Parameters

Name	Where	How to get	Example
`agent_id`	Path	Verified passport JWT → claims.sub (agent_id).	`agt_ag_alpha`

Example response

{
  "ok": true,
  "data": {
    "agent_id": "agt_ag_alpha",
    "user_id": "own_main",
    "user_kyc_level": 2,
    "agent_reputation": 5,
    "display_name": "Alpha Agent",
    "avatar_url": "https://cdn.example.com/agt_ag_alpha.png",
    "description": "Autonomous trading assistant",
    "status": "active"
  }
}

GET/core/.well-known/jwks.jsonJWKS (public keys)

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.

No authentication required

Example request

curl
  -sS
  -X GET
  -H "Accept: application/json"
  "https://lime.pics/api/v1/core/.well-known/jwks.json"

Example response

{
  "keys": [
    {
      "kty": "RSA",
      "kid": "lime-core-1",
      "use": "sig",
      "alg": "RS256",
      "n": "...",
      "e": "AQAB"
    }
  ]
}

SDK and libraries

Python Agent SDK

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).

Architecture: ADR 0059 in the LIME monorepo docs.

# pip install lime-agents-sdk
# https://github.com/Mawyxx/lime-agents-sdk
# Full Python API: https://lime-agents-sdk.readthedocs.io/
import asyncio
from lime_agents import LimeAgent

async def main() -> None:
    agent = LimeAgent()  # LIME_AGENT_TOKEN
    result = await agent.login("{login_request_id}")
    print(result.status)

asyncio.run(main())

Variable	Description
`LIME_AGENT_TOKEN`	Agent secret from user portal (required)
`LIME_API_BASE`	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 (same material as other LIME APIs). No request body. Any agent with a valid token may obtain an MCP access JWT.

Flow: discover metadata (RFC 8414 raw JSON at GET /api/v1/modules/oauth/.well-known/oauth-authorization-server or issuer-root alias) → POST token with X-Agent-Token header only → your MCP RS verifies the JWT with Core JWKS (RFC 7517 raw keys). Use lime-mcp-server-sdk v0.5.0+ (github.com/Mawyxx/lime-mcp-server-sdk) or see MCP Server SDK below.

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). Default audience is mcp. Passport-specific claims (user_id, request_id) are never present in MCP tokens.

Request MCP access token

# client_credentials — authenticate with X-Agent-Token (same opaque value as LIME APIs)
curl -sS -X POST "https://lime.pics/api/v1/modules/oauth/token" \
  -H "Accept: application/json" \
  -H "X-Agent-Token: {your_agent_token}"

Discover Authorization Server metadata

# RFC 8414 metadata (raw JSON — read issuer, jwks_uri at top level)
curl -sS "https://lime.pics/api/v1/modules/oauth/.well-known/oauth-authorization-server"
# Also at issuer root (nginx alias):
# curl -sS "https://lime.pics/.well-known/oauth-authorization-server"
# Example response (full discovery document):
# {"issuer":"https://lime.pics","authorization_endpoint":"https://lime.pics/api/v1/modules/oauth/authorize","token_endpoint":"https://lime.pics/api/v1/modules/oauth/token","jwks_uri":"https://lime.pics/api/v1/core/.well-known/jwks.json","registration_endpoint":"https://lime.pics/api/v1/modules/oauth/register","grant_types_supported":["authorization_code","client_credentials"],"response_types_supported":["code"],"scopes_supported":["mcp"],"token_endpoint_auth_methods_supported":["none"],"code_challenge_methods_supported":["S256"],"lime_agent_token_header":"X-Agent-Token","lime_token_request_body":"grant_type","lime_default_audience":"mcp"}

Verify MCP JWT on your resource server (lime-mcp-server-sdk)

# pip install lime-mcp-server-sdk
# https://github.com/Mawyxx/lime-mcp-server-sdk
# Full Python API: https://lime-mcp-server-sdk.readthedocs.io/
from lime_mcp_server import TokenVerifier

verifier = TokenVerifier()  # LIME_BASE_URL, LIME_OAUTH_AUDIENCE from env
result = verifier.verify("{access_token_from_oauth_token_response}")
if result.is_valid:
    print(result.agent_id)  # alias for claims["sub"] (agent UUID)

Variable	Description
`LIME_AGENT_TOKEN`	Agent secret — X-Agent-Token on /oauth/token (required)
`LIME_API_BASE`	API root (optional, default https://lime.pics/api/v1)

Python MCP Server SDK

Install lime-mcp-server-sdk v0.5.0+ from PyPI (pypi.org/project/lime-mcp-server-sdk) or GitHub (github.com/Mawyxx/lime-mcp-server-sdk). TokenVerifier fetches raw RFC 8414 metadata and Core JWKS (RFC 7517 top-level keys), and verifies RS256 MCP JWTs.

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). 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.

Verify MCP JWT with TokenVerifier

# pip install lime-mcp-server-sdk
# https://github.com/Mawyxx/lime-mcp-server-sdk
# Full Python API: https://lime-mcp-server-sdk.readthedocs.io/
from lime_mcp_server import TokenVerifier

verifier = TokenVerifier()
result = verifier.verify("{bearer_mcp_jwt}")
if result.is_valid:
    print(result.agent_id)  # alias for claims["sub"]

Variable	Description
`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 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 the login flow.

Python API reference: lime-sites-sdk.readthedocs.io — FastAPI patterns, verify_passport, and SSE notes.

Requires LIME_SITE_TOKEN on the site backend. Verify agent_passport_jwt with JWKS via LimeSite.verify_passport() or your own PyJWT path.

Agent Binding methods are not in the SDK yet — use HTTP POST /modules/bindings/requests + JWKS aud=lime-binding (see Agent Binding guide above). Architecture: ADR 0060 / ADR 0087.

Create + on_login with LimeSite

# pip install lime-sites-sdk
# https://github.com/Mawyxx/lime-site-sdk
# Full Python API: https://lime-sites-sdk.readthedocs.io/
import asyncio
from lime_sites import LimeSite

async def main() -> None:
    received = asyncio.Event()
    box: dict[str, object] = {}
    site = LimeSite()  # LIME_SITE_TOKEN; starts SSE dispatcher

    @site.on_login
    async def handle_login(request_id: str, passport: str | None) -> None:
        box["request_id"] = request_id
        box["passport"] = passport
        received.set()

    req = await site.create_login_request()
    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,
        )
        print(verified.valid)
    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)

40% of MCP servers have no authentication

Site login

Site backend · header X-Site-Token

Agent

Agent worker · fetch PoW (public) · approve with X-Agent-Token

OAuth for MCP

Machine-only Authorization Server · client_credentials · JWT for external MCP RS

Core / Public keys

Verify passport JWTs · public JWKS · agent profiles · no auth

Site login

Site backend · header X-Site-Token

Agent

Agent worker · fetch PoW (public) · approve with X-Agent-Token

OAuth for MCP

Machine-only Authorization Server · client_credentials · JWT for external MCP RS

Core / Public keys

Verify passport JWTs · public JWKS · agent profiles · no auth

Documentation

Integration API

Base URL: https://lime.pics/api/v1

Scenario guides

New to LIME? Pick the scenario that matches your role. Each guide explains context, prerequisites, who does what, and numbered steps with copy-paste examples.

Zero Human Auth (site)

Passwordless headless login for AI agents on your product: your server creates the request, listens on SSE, and verifies a cryptographic passport — no browser OAuth at runtime.

Agent Binding (site)

Two-click linking: your user connects their LIME agent to a local account via browser redirect — your backend only creates the request and verifies the callback passport.

MCP server (passport verification)

Secure your MCP tools: verify LIME JWTs locally with JWKS, trust claims.sub as agent_id — no calls back to LIME per request.

Agent programmatic access (MCP)

Teach your bot to fetch MCP JWTs from LIME and call federated tools with Bearer — machine-only, no browser.

Agent programmatic access (Zero Human Auth)

Your bot approves a site login headlessly: fetch PoW, solve it, call approve — no browser, no site_token, no SSE on your side.

Open all guides →

Endpoints

Site login

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

Name	Location	Type	Required
X-Site-Token	header	string	No

Example request

curl
  -sS
  -N
  -X GET
  -H "Accept: application/json"
  -H "X-Site-Token: {your_site_token}"
  "https://lime.pics/api/v1/modules/agent-login/events"

Parameters

Name	Where	How to get	Example
`X-Site-Token`	Header	Owner portal → register site → copy site_token once (header X-Site-Token, prefix st_…).	`st_site_main_…`

Example SSE data payload

{
  "type": "approved",
  "login_request_id": "lr_flow_demo",
  "status": "approved",
  "agent_passport_jwt": "eyJhbG..."
}

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).

POST/modules/agent-login/requestsCreate login request

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)

Name	Location	Type	Required
X-Site-Token	header	string	No

Example request

curl
  -sS
  -X POST
  -H "Accept: application/json"
  -H "X-Site-Token: {your_site_token}"
  "https://lime.pics/api/v1/modules/agent-login/requests"
  -H "Content-Type: application/json"
  -d '{}'

Parameters

Name	Where	How to get	Example
`X-Site-Token`	Header	Owner portal → register site → copy site_token once (header X-Site-Token, prefix st_…).	`st_site_main_…`

Example response

{
  "ok": true,
  "data": {
    "login_request_id": "lr_flow_demo",
    "status": "PENDING",
    "expires_at": "2026-06-02T12:02:00Z"
  }
}

GET/modules/agent-login/requests/{request_id}Get login request status

Poll request status from your backend. Caller site_id must match the row (via X-Site-Token). Returns status only — no JWT in the body.

Header: X-Site-Token

Name	Location	Type	Required
request_id	path	string	Yes
X-Site-Token	header	string	No

Example request

curl
  -sS
  -X GET
  -H "Accept: application/json"
  -H "X-Site-Token: {your_site_token}"
  "https://lime.pics/api/v1/modules/agent-login/requests/{request_id}"

Parameters

Name	Where	How to get	Example
`request_id`	Path	Response of POST /modules/agent-login/requests → data.login_request_id.	`lr_flow_demo`
`X-Site-Token`	Header	Owner portal → register site → copy site_token once (header X-Site-Token, prefix st_…).	`st_site_main_…`

Example response

{
  "ok": true,
  "data": {
    "login_request_id": "lr_flow_demo",
    "status": "PENDING",
    "expires_at": "2026-06-02T12:02:00Z"
  }
}

POST/modules/bindings/requestsCreate agent binding request

Header: X-Site-Token

Name	Location	Type	Required
X-Site-Token	header	string	No

Example request

curl
  -sS
  -X POST
  -H "Accept: application/json"
  -H "X-Site-Token: {your_site_token}"
  "https://lime.pics/api/v1/modules/bindings/requests"
  -H "Content-Type: application/json"
  -d '{"redirect_uri":"https://mysite.example/binding-callback"}'

Example response

{
  "ok": true,
  "data": {
    "binding_id": "bnd_a1b2c3d4e5f6",
    "connect_url": "https://lime.pics/connect/?binding_id=bnd_a1b2c3d4e5f6",
    "status": "PENDING",
    "expires_at": "2026-07-16T12:10:00Z"
  }
}

Agent

GET/auth/requests/{request_id}Get login request for agent (SDK)

Public (agent worker, no tokens)

Name	Location	Type	Required
request_id	path	string	Yes

Example request

curl
  -sS
  -X GET
  -H "Accept: application/json"
  "https://lime.pics/api/v1/auth/requests/{request_id}"

Parameters

Name	Where	How to get	Example
`request_id`	Path	Site backend passes login_request_id to your agent worker (from the create response).	`lr_flow_demo`

Example response

{
  "ok": true,
  "data": {
    "request_id": "lr_flow_demo",
    "status": "PENDING",
    "pow_challenge": "xK9mP2nQ7vR4sT1uW8yZ0aB3cD6eF",
    "pow_difficulty": 15,
    "expires_at": "2026-06-02T12:02:00Z"
  }
}

GET/core/agents/me/profileGet agent profile

Authenticated agent read (X-Agent-Token). For site UI after login without agent token, use GET /agents/{agent_id}.

Header: X-Agent-Token

Name	Location	Type	Required
X-Agent-Token	header	string	No
Authorization	header	string	No

Example request

curl
  -sS
  -X GET
  -H "Accept: application/json"
  -H "X-Agent-Token: {your_agent_token}"
  -H "Authorization: {your_authorization}"
  "https://lime.pics/api/v1/core/agents/me/profile"

Parameters

Name	Where	How to get	Example
`X-Agent-Token`	Header	Owner portal → create agent → copy agent_token once (header X-Agent-Token, prefix at_…).	`at_ag_alpha_…`

Example response

{
  "ok": true,
  "data": {
    "agent_id": "agt_ag_alpha",
    "user_id": "own_main",
    "user_kyc_level": 2,
    "agent_reputation": 5,
    "display_name": "My Agent",
    "avatar_url": null,
    "description": null
  }
}

POST/modules/agent-login/requests/{request_id}/approveApprove login request

Header: X-Agent-Token (agent secret)

Name	Location	Type	Required
request_id	path	string	Yes
X-Agent-Token	header	string	No
Authorization	header	string	No

Example request

curl
  -sS
  -X POST
  -H "Accept: application/json"
  -H "X-Agent-Token: {your_agent_token}"
  -H "Authorization: {your_authorization}"
  "https://lime.pics/api/v1/modules/agent-login/requests/{request_id}/approve"
  -H "Content-Type: application/json"
  -d '{"pow_nonce":"12345678"}'

Parameters

Name	Where	How to get	Example
`request_id`	Path	Response of POST /modules/agent-login/requests → data.login_request_id.	`lr_flow_demo`
`X-Agent-Token`	Header	Owner portal → create agent → copy agent_token once (header X-Agent-Token, prefix at_…).	`at_ag_alpha_…`
`pow_nonce`	Body	Proof-of-Work solution: nonce where SHA-256(challenge+nonce) < 2^(256−difficulty). Challenge from GET /auth/requests/{id} (canonical SDK endpoint). Same-agent delivery retry on APPROVED skips PoW verification.	`12345678`

Example response

{
  "ok": true,
  "data": {
    "request_id": "lr_flow_demo",
    "site_id": "site_main",
    "status": "DELIVERED",
    "expires_at": "2026-06-02T12:02:00Z",
    "approved_agent_id": "agt_ag_alpha"
  }
}

OAuth for MCP

GET/modules/oauth/.well-known/oauth-authorization-serverOAuth Authorization Server metadata

No authentication required. IP rate limit applies.

Example request

curl
  -sS
  -X GET
  -H "Accept: application/json"
  "https://lime.pics/api/v1/modules/oauth/.well-known/oauth-authorization-server"

Example response

{
  "issuer": "https://lime.pics",
  "authorization_endpoint": "https://lime.pics/api/v1/modules/oauth/authorize",
  "token_endpoint": "https://lime.pics/api/v1/modules/oauth/token",
  "jwks_uri": "https://lime.pics/api/v1/core/.well-known/jwks.json",
  "registration_endpoint": "https://lime.pics/api/v1/modules/oauth/register",
  "grant_types_supported": [
    "authorization_code",
    "client_credentials"
  ],
  "response_types_supported": [
    "code"
  ],
  "scopes_supported": [
    "mcp"
  ],
  "token_endpoint_auth_methods_supported": [
    "none"
  ],
  "code_challenge_methods_supported": [
    "S256"
  ],
  "lime_agent_token_header": "X-Agent-Token",
  "lime_token_request_body": "grant_type",
  "lime_default_audience": "mcp"
}

POST/modules/oauth/tokenOAuth token (client_credentials)

Header: X-Agent-Token (same opaque agent token as LIME APIs). Valid agent token is sufficient for MCP JWT issuance.

Name	Location	Type	Required
X-Agent-Token	header	string	Yes

Example request

curl
  -sS
  -X POST
  -H "Accept: application/json"
  -H "X-Agent-Token: {your_agent_token}"
  "https://lime.pics/api/v1/modules/oauth/token"

Parameters

Name	Where	How to get	Example
`X-Agent-Token`	Header	Same opaque secret as LIME APIs (LIME_AGENT_TOKEN). Sent as X-Agent-Token header on POST /modules/oauth/token.	`at_ag_alpha_…`

Example response

{
  "access_token": "eyJhbG...",
  "token_type": "Bearer",
  "expires_in": 3600
}

Core / Public keys

GET/agents/{agent_id}Get public agent profile

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).

Name	Location	Type	Required
agent_id	path	string	Yes

Example request

curl
  -sS
  -X GET
  -H "Accept: application/json"
  "https://lime.pics/api/v1/agents/{agent_id}"

Parameters

Name	Where	How to get	Example
`agent_id`	Path	Verified passport JWT → claims.sub (agent_id).	`agt_ag_alpha`

Example response

{
  "ok": true,
  "data": {
    "agent_id": "agt_ag_alpha",
    "user_id": "own_main",
    "user_kyc_level": 2,
    "agent_reputation": 5,
    "display_name": "Alpha Agent",
    "avatar_url": "https://cdn.example.com/agt_ag_alpha.png",
    "description": "Autonomous trading assistant",
    "status": "active"
  }
}

GET/core/.well-known/jwks.jsonJWKS (public keys)

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.

No authentication required

Example request

curl
  -sS
  -X GET
  -H "Accept: application/json"
  "https://lime.pics/api/v1/core/.well-known/jwks.json"

Example response

{
  "keys": [
    {
      "kty": "RSA",
      "kid": "lime-core-1",
      "use": "sig",
      "alg": "RS256",
      "n": "...",
      "e": "AQAB"
    }
  ]
}

SDK and libraries

Python Agent SDK

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).

Architecture: ADR 0059 in the LIME monorepo docs.

# pip install lime-agents-sdk
# https://github.com/Mawyxx/lime-agents-sdk
# Full Python API: https://lime-agents-sdk.readthedocs.io/
import asyncio
from lime_agents import LimeAgent

async def main() -> None:
    agent = LimeAgent()  # LIME_AGENT_TOKEN
    result = await agent.login("{login_request_id}")
    print(result.status)

asyncio.run(main())

Variable	Description
`LIME_AGENT_TOKEN`	Agent secret from user portal (required)
`LIME_API_BASE`	API root (optional, default https://lime.pics/api/v1)

MCP OAuth (Authorization Server)

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). Default audience is mcp. Passport-specific claims (user_id, request_id) are never present in MCP tokens.

Request MCP access token

# client_credentials — authenticate with X-Agent-Token (same opaque value as LIME APIs)
curl -sS -X POST "https://lime.pics/api/v1/modules/oauth/token" \
  -H "Accept: application/json" \
  -H "X-Agent-Token: {your_agent_token}"

Discover Authorization Server metadata

# RFC 8414 metadata (raw JSON — read issuer, jwks_uri at top level)
curl -sS "https://lime.pics/api/v1/modules/oauth/.well-known/oauth-authorization-server"
# Also at issuer root (nginx alias):
# curl -sS "https://lime.pics/.well-known/oauth-authorization-server"
# Example response (full discovery document):
# {"issuer":"https://lime.pics","authorization_endpoint":"https://lime.pics/api/v1/modules/oauth/authorize","token_endpoint":"https://lime.pics/api/v1/modules/oauth/token","jwks_uri":"https://lime.pics/api/v1/core/.well-known/jwks.json","registration_endpoint":"https://lime.pics/api/v1/modules/oauth/register","grant_types_supported":["authorization_code","client_credentials"],"response_types_supported":["code"],"scopes_supported":["mcp"],"token_endpoint_auth_methods_supported":["none"],"code_challenge_methods_supported":["S256"],"lime_agent_token_header":"X-Agent-Token","lime_token_request_body":"grant_type","lime_default_audience":"mcp"}

Verify MCP JWT on your resource server (lime-mcp-server-sdk)

# pip install lime-mcp-server-sdk
# https://github.com/Mawyxx/lime-mcp-server-sdk
# Full Python API: https://lime-mcp-server-sdk.readthedocs.io/
from lime_mcp_server import TokenVerifier

verifier = TokenVerifier()  # LIME_BASE_URL, LIME_OAUTH_AUDIENCE from env
result = verifier.verify("{access_token_from_oauth_token_response}")
if result.is_valid:
    print(result.agent_id)  # alias for claims["sub"] (agent UUID)

Variable	Description
`LIME_AGENT_TOKEN`	Agent secret — X-Agent-Token on /oauth/token (required)
`LIME_API_BASE`	API root (optional, default https://lime.pics/api/v1)

Python MCP Server SDK

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). 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.

Verify MCP JWT with TokenVerifier

# pip install lime-mcp-server-sdk
# https://github.com/Mawyxx/lime-mcp-server-sdk
# Full Python API: https://lime-mcp-server-sdk.readthedocs.io/
from lime_mcp_server import TokenVerifier

verifier = TokenVerifier()
result = verifier.verify("{bearer_mcp_jwt}")
if result.is_valid:
    print(result.agent_id)  # alias for claims["sub"]

Variable	Description
`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

Python API reference: lime-sites-sdk.readthedocs.io — FastAPI patterns, verify_passport, and SSE notes.

Requires LIME_SITE_TOKEN on the site backend. Verify agent_passport_jwt with JWKS via LimeSite.verify_passport() or your own PyJWT path.

Agent Binding methods are not in the SDK yet — use HTTP POST /modules/bindings/requests + JWKS aud=lime-binding (see Agent Binding guide above). Architecture: ADR 0060 / ADR 0087.

Create + on_login with LimeSite

# pip install lime-sites-sdk
# https://github.com/Mawyxx/lime-site-sdk
# Full Python API: https://lime-sites-sdk.readthedocs.io/
import asyncio
from lime_sites import LimeSite

async def main() -> None:
    received = asyncio.Event()
    box: dict[str, object] = {}
    site = LimeSite()  # LIME_SITE_TOKEN; starts SSE dispatcher

    @site.on_login
    async def handle_login(request_id: str, passport: str | None) -> None:
        box["request_id"] = request_id
        box["passport"] = passport
        received.set()

    req = await site.create_login_request()
    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,
        )
        print(verified.valid)
    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)

40% of MCP servers have no authentication

LIME API — Site Login, JWKS & MCP OAuth · LIME

Integration API

Scenario guides

Zero Human Auth (site)

Agent Binding (site)

MCP server (passport verification)

Agent programmatic access (MCP)

Agent programmatic access (Zero Human Auth)

Endpoints

Site login

Agent

OAuth for MCP

Core / Public keys

SDK and libraries

Python Agent SDK

MCP OAuth (Authorization Server)

Python MCP Server SDK

Python Site SDK

Related reading

Integration API

Scenario guides

Zero Human Auth (site)

Agent Binding (site)

MCP server (passport verification)

Agent programmatic access (MCP)

Agent programmatic access (Zero Human Auth)

Endpoints

Site login

Agent

OAuth for MCP

Core / Public keys

SDK and libraries

Python Agent SDK

MCP OAuth (Authorization Server)

Python MCP Server SDK

Python Site SDK

Related reading