Authentication methods and token lifecycle

Protected /api/v1 routes accept Authorization: Bearer {token} or the same API key in the x-agent-api-key header. Accepted credentials: primary workspace API key (format: agk_<base64>.<base64>) or a 30-day access token. Access tokens expire after 2,592,000 seconds. Credentials carry explicit scopes (e.g., traces:write, gateway:check, agent_commands:read).

The exchange route is unauthenticated. Send the API key in x-agent-api-key or as api_key in the JSON body. A Bearer token on this route returns 400 "This endpoint accepts an API key (agk_...), not a Bearer token." A revoked or archived key is 401 (api_key_revoked / api_key_archived). 403 is only service_agent_inactive, insufficient_scopes, or workspace_frozen|workspace_paused|workspace_archived.

POST /api/v1/socket_tokens mints a 600-second token for /socket. The caller must already be authenticated on the machine API and must hold the exact scope sockets:connect. Frozen, paused, or archived workspaces are refused with 403 workspace_frozen|workspace_paused|workspace_archived before the controller runs.

Owners and admins generate, rotate, and delete the workspace primary API key at /app/agents/workspace-key. It lives on a hidden account-api service agent that never appears in GET /api/v1/operator/service_agents, has no operator REST, and always has credentials:write stripped from its scopes.

Transport: session cookie (_agent_ops_key) set after login. Session lifetime: 14 days. Tokens older than 7 days are automatically reissued. Remember me cookie: _agent_ops_web_user_remember_me (14-day max age). Operator socket identity is tied to the authenticated session.

Transport: HTTP Authorization: Bearer {scim_token}. Tokens are created and revoked on Workspace admin at /app/admin, not on /app/workspace. Endpoints: all routes under /scim/v2/*. Content type: application/scim+json. SCIM tokens do not expire; rotate by creating a new token and revoking the old one on /app/admin.

A signed-out user requests a reset at /users/forgot-password. The response is identical whether or not the address has an account: the page always states that a link was sent if the address has one, and never echoes the address back, so nothing on it can be used as an account-existence oracle. Requests are throttled per IP and per address (10 and 5 respectively per 15 minutes), and a throttled submit renders that same panel.

The link is single use and expires 60 minutes after it is issued. Following it opens /users/reset-password/:token. Changing the account's email address or suspending the account invalidates outstanding links. An unknown, expired, or already-used token renders one dead-end panel with a link back to request a new one.

Setting a new password deletes every token the user holds -- remaining reset links and all browser sessions -- and live sessions are disconnected immediately. An unconfirmed account is confirmed by the reset, since receiving the emailed link proves control of the address. Issuing a new link never invalidates one already in the inbox.

Partner routes authenticate Authorization: Bearer mpk_… via PartnerAuth, not an agk_ key. Engagement ingest authenticates an engagement token, not a workspace key. Both planes throttle failed authentications at 30 HTTP 401/403 responses per client address per 60 seconds, then return the shared 429 problem.