Let an agent sign into your site

You need

• “Sign in with LIME” button + waiting screen that shows login_request_id
• Backend that can set a session cookie
• LIME_SITE_TOKEN only on that backend

Steps

1. 1

   Create the login request on button click

   When the browser hits Sign in with LIME, call create_login_request. Put login_request_id on the waiting screen — that screen is how the agent gets the ID.

   PythoncURL

   Copy

   import asyncio
   from lime_sites import LimeSite
   
   LIME_SITE_TOKEN = "LIME_SITE_TOKEN_HERE"
   
   async def main() -> None:
       site = LimeSite(site_token=LIME_SITE_TOKEN)
       req = await site.create_login_request()
       print("login_request_id:", req.request_id)
       # Show req.request_id on the waiting screen in the browser.
       await site.aclose()
   
   asyncio.run(main())

   AssertResponse includes login*request_id (lr*…); waiting UI shows the ID.

2. 2

   Wait for approval over SSE

   Keep GET …/events with X-Site-Token while the page waits. When the agent approves, the event carries the passport JWT for this request_id. Treat **login_request_id as the SSE idempotency key** — Redis delivery is at-least-once; duplicate APPROVED frames for the same id must not mint a second site session.

   PythoncURL

   Copy

   import asyncio
   from lime_sites import LimeSite
   
   LIME_SITE_TOKEN = "LIME_SITE_TOKEN_HERE"
   
   async def main() -> None:
       received = asyncio.Event()
       box: dict[str, object] = {}
   
       site = LimeSite(site_token=LIME_SITE_TOKEN)
   
       @site.on_login
       async def handle_login(request_id: str, passport: str | None) -> None:
           box["request_id"] = request_id
           box["passport"] = passport
           received.set()
   
       await asyncio.wait_for(received.wait(), timeout=120)
       print(box.get("request_id"), bool(box.get("passport")))
       await site.aclose()
   
   asyncio.run(main())

   AssertSSE delivers passport JWT for the same login_request_id.

3. 3

   Verify JWT and open the session

   verify_passport (signature, aud=lime-site-login, expected request_id). Read agent_id and set your normal site cookie — same as a human login.

   Python

   Copy

   import asyncio
   from lime_sites import LimeSite
   
   LIME_SITE_TOKEN = "LIME_SITE_TOKEN_HERE"
   PASSPORT_JWT = "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."
   LOGIN_REQUEST_ID = "lr_xxxxxxxx"
   
   async def main() -> None:
       site = LimeSite(site_token=LIME_SITE_TOKEN)
       verified = await site.verify_passport(
           PASSPORT_JWT,
           expected_request_id=LOGIN_REQUEST_ID,
       )
       agent_id = verified.claims["agent_id"]
       # Set YOUR site session cookie for agent_id — LIME does not create it.
       print("signed_in_agent_id:", agent_id)
       await site.aclose()
   
   asyncio.run(main())

   AssertClaims.agent_id present; site session cookie issued for that agent_id.

Related API

• POSTCreate login request
• GETWait for site login events (SSE)
• GETGet login request status
• GETJWKS (public keys)
• GETGet public agent profile