Agent Binding (site)

When to use this guide

• You already have human users with sessions and want to attach a LIME agent_id to that account.
• Runtime login for agents may still use Zero Human Auth — binding is a separate one-time linking step.
• You can redirect the user's browser to LIME /connect for agent selection.

Before you start

1. site_token on your backend (same as Zero Human Auth setup).
2. A logged-in user session on your site (you decide when binding is offered).
3. redirect_uri on your domain that accepts the callback with binding_id context in your session.
4. JWKS verification code (same stack as site login passports).

Who does what

Your code (site backend)

Only what you implement in this role. No PoW, SSE, or token logic from the partner side — that is in a separate guide.

1. 1

   Site backend

   Prepare your user session

   When the user clicks “Connect LIME agent”, ensure they are authenticated on your site. You will store binding_id server-side before redirecting — do not trust binding_id from the client alone.

   Tip: Binding helpers are not in lime-sites-sdk yet; use raw HTTP + your callback handler.

2. 2

   Site backend

   Create a binding request

   POST with X-Site-Token, binding_id from your pending session, and redirect_uri where LIME sends the user back. Save binding_id and connect_url from the response.

   Your server — create binding request

   Copy

   # Site backend — start Agent Binding (store binding_id in your session before redirect)
   curl -sS -X POST "https://lime.pics/api/v1/modules/bindings/requests" \
     -H "Accept: application/json" \
     -H "Content-Type: application/json" \
     -H "X-Site-Token: {your_site_token}" \
     -d '{"redirect_uri":"https://yoursite.example/binding-callback"}'
   # Response data: binding_id, connect_url, status, expires_at (600s)
   # Redirect the browser to connect_url (lime.pics/connect/?binding_id=…)

3. 3

   Site backend → Human

   Redirect the browser to connect_url

   HTTP 302 the user to connect_url. They land on lime.pics/connect (session required), see their agents, and confirm binding. Portal routes GET /public and POST /complete are internal — your site must not call them.

4. 4

   Site backend

   Handle callback and verify passport

   On redirect_uri, read the binding passport JWT from the query/body per your integration. Verify via JWKS: iss=https://lime.pics, aud=lime-binding, binding_id matches what you stored, then save agent_id for this user.

   Your server — verify on callback

   Copy

   # On your redirect_uri callback: ?passport=<JWT>
   # 1. Fetch JWKS (cache by kid)
   curl -sS "https://lime.pics/api/v1/core/.well-known/jwks.json"
   # 2. Verify RS256, iss, aud=lime-binding, exp (passport TTL 60s)
   # 3. REQUIRE claim binding_id == the value you stored before redirect
   # 4. Map claims.sub (agent id) / user_id → your local account
   # Do NOT call GET …/public or POST …/complete — those are LIME portal UI-only

Related endpoints

• POSTCreate agent binding request
• GETJWKS (public keys)