Decision table
API key + REST HMAC
OAuth (assistants)
PKCE authorization code flow. Access tokens last 1 hour. There is no refresh token today: re-run the consent flow or use long-lived API keys for headless servers.Inbound webhook HMAC
Scopes
OAuth and API keys share the same scope strings. Prefer theread:* / write:* form:
Legacy aliases (
agents:read, bots:write, etc.) still work.
MCP authentication
Send the same API key or OAuth token on every MCP request, includinginitialize. Sessions are credential-bound. See MCP Server.
Protected endpoints
All/api/v1/* routes (except public marketplace browse and inbound webhooks) require authentication. The API Reference playground may label auth as optional for try-it convenience; production calls must include credentials.