Authentication

Last verified: 2026-06-20 (Task #390 — User APIs documentation).

The Agent Runs API shares the end-user authentication model used by the Trips & Itinerary and Events APIs. There are no tm_ developer keys here.

Two ways to authenticate

A request with neither returns 401 ({ "error": "Authentication required" }).

Owner scoping

Runs are owner-scoped, which is stricter than trip membership:

• Reading, polling, streaming, controlling, and pinning a run all require that the run's userId equals the authenticated user. Another user — even a collaborator on the same trip — gets 403.
• Creating a run requires that you own the target trip (the trip's userId equals the authenticated user). Otherwise the create returns 403, and a missing trip returns 404.

The SSE stream is cookie-only

GET /v1/agent-runs/{runId}/stream is a Server-Sent Events endpoint. Because the browser EventSource API cannot attach custom headers, this endpoint authenticates with the session cookie only — a bearer token in the Authorization header is not read here. Every other endpoint accepts either credential. See streaming.md.

Using the Try It console

The interactive API reference ships a Try It console. Authorize it with a bearer token (the console does not forward cookies). Note that the SSE stream endpoint cannot be exercised from the cookie-less console — use the events polling endpoint there instead.