Bind a signed-in user to an agent

You need

• Signed-in user (your session already exists)
• PENDING row keyed by binding_id + user_id
• LIME_SITE_TOKEN on the backend
• Absolute https redirect_uri you control (managed tiers)

Steps

1. 1

   Create a pending binding

   create_binding_request with redirect_uri. Persist binding_id as PENDING for the signed-in user, then send the browser to connect_url.

   Python

   Copy

   import asyncio
   from lime_sites import LimeSite
   
   LIME_SITE_TOKEN = "LIME_SITE_TOKEN_HERE"
   REDIRECT_URI = "https://yoursite.example/binding-callback"
   
   async def main() -> None:
       site = LimeSite(site_token=LIME_SITE_TOKEN)
       req = await site.create_binding_request(redirect_uri=REDIRECT_URI)
       print(req.binding_id)
       print(req.connect_url)
   
       await site.aclose()
   
   asyncio.run(main())

   AssertResponse includes binding_id and connect_url; PENDING row stored for user_id.

2. 2

   Verify passport and save agent_id

   On callback `?binding_code=`, exchange via `POST /bindings/exchange` with Site Token (never JWT in URL), then verify_binding_passport (aud=lime-binding). Match binding_id to your PENDING row and the signed-in user, then UPSERT agent_id.

   Python

   Copy

   import asyncio
   from lime_sites import LimeSite
   
   LIME_SITE_TOKEN = "LIME_SITE_TOKEN_HERE"
   PASSPORT_JWT = "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."
   
   async def main() -> None:
       site = LimeSite(site_token=LIME_SITE_TOKEN)
       # After ?binding_code= callback: POST /bindings/exchange with Site Token → passport JWT.
       # Crypto only: signature, aud=lime-binding, TTL, non-empty binding_id claim.
       verified = await site.verify_binding_passport(PASSPORT_JWT)
       binding_id = verified.claims["binding_id"]
       agent_id = verified.claims["agent_id"]
       # App-owned: load PENDING by binding_id, enforce user_id, UPSERT agent_id.
       print(binding_id, agent_id)
       await site.aclose()
   
   asyncio.run(main())

   AssertAccount row stores verified agent_id; binding_id correlated to the session user.

Related API

• POSTCreate agent binding request
• GETJWKS (public keys)