Authentication
Authenticate REST requests and understand the separate Account and grant authorization boundary.
Send a WorkOS user access token, Agent Registration credential, or provisioned agent API key as an HTTP bearer token:
Authorization: Bearer YOUR_TOKENFor unattended services, store the value in a secret manager and expose it to the process as COMBINED_TOKEN. Never place it in a URL, source name, SQL text, log statement, support bundle, repository, or client-side application bundle.
curl -fsS "$COMBINED_API_URL/v1/accounts" \
-H "Authorization: Bearer $COMBINED_TOKEN" \
-H "Accept: application/json"Authentication is not authorization
The credential identifies a principal. Each operation then evaluates Account membership or role, Source and dataset grants, expiry, row and byte limits, rate limits, and current grant version. A valid token can therefore receive 403 for an Account or Source it cannot use.
Most account-specific REST operations carry accountId as a query or body field. Use GET /v1/accounts to discover visible accounts; never guess an Account UUID. MCP instead fixes account scope in its endpoint URL.
Credential lifecycle
Agent credentials are displayed once. Rotate by revoking the old principal or credential and issuing a replacement. Revocation changes the Account grant version; a query that started under an obsolete version is discarded before result delivery.
On 401, obtain a fresh credential or complete the advertised OAuth flow. Do not repeatedly retry the same rejected bearer token. On 403, change the grant or requested scope through an authorized owner/deployer workflow rather than attempting a different identifier.
MCP OAuth discovery
This page describes REST headers. An OAuth-capable MCP client should connect directly to /mcp?account_id=... and follow the WWW-Authenticate protected-resource metadata challenge. See MCP for that flow.