An agent often cannot finish on its own: a person has to approve a payment or verify an email. When your server sends that person a link, add a handoff token to it, and the person's actions count toward the agent's journey: their checkout is credited to the agent that brought them.
1. While the agent is on journey J (the journey key of its requests), ask for a token:
curl -sS -X POST "https://alg.katrinalaszlo.com/v1/handoffs" \
-H "Authorization: Bearer $AGENT_TRAFFIC_KEY" \
-H "Content-Type: application/json" \
-d '{ "journey_id": "j_4f9c0e7a2b6d4e1f8a3c5b7d9e0f1a2b" }'It answers 201:
{ "token": "h_Q2x2c1Zx0m4bX7yQe9Rk3vT8pLw6nJ5aHc1dGf2sUoA", "param": "track_h", "journey_id": "j_4f9c0e7a2b6d4e1f8a3c5b7d9e0f1a2b", "expires_at": "2026-10-24T18:00:00.000Z" }2. Append it to the link you send: https://example.com/checkout?plan=pro&track_h=h_Q2x2…. 3. When the person's request arrives with ?track_h=, send its value as handoff_token on that request's event. Agent traffic stores that event on J with journey_source handoff, and its 202 lists the event under journeys:
{ "accepted": 1, "rejected": [], "journeys": [{ "idempotency_key": "req_9a1b", "journey_id": "j_4f9c0e7a2b6d4e1f8a3c5b7d9e0f1a2b", "journey_source": "handoff" }] }4. Carry J on the person's later requests: set the track_j cookie to it in your response, so their sign-in and checkout land on the agent's journey too.
A token links once, to the first event that brings it back, and stops linking 24 hours after it was created. Agent traffic stores only its SHA-256, never the token, so treat the link like any one-time link: send it to the person only. An event with a token that is unknown, expired, already used or from another project is still stored, on its own journey key if it had one, and its 202 carries a warning under event_warnings instead of journeys: { "idempotency_key", "warning": "handoff_not_linked", "message" }. The warning never says which of those it was. A value that is not a token shape is rejected with invalid_handoff_token. A project can create 60 tokens a minute; past that POST /v1/handoffs answers 429 rate_limited.
The person usually signs in as the account the agent worked for, which is the point: their payment lands in the agent's session. If a different account signs in on that journey, it gets a session of its own as on any shared browser (section 4), and its payments are never credited to the agent's account.
With the @katrinalaszlo/track package from 0.7.0, await traffic.handoffUrl(link, { req }) adds the token for the journey of the current request, and the middleware does steps 3 and 4: a request with ?track_h= waits up to 2 seconds for agent traffic to link it, records a handoff_opened event, and, with issueJourneyKeys on, sets the person's track_j cookie to the agent's journey.