Authentication

Authentication proves the principal; grants decide what that principal can do. A valid credential never implies access to every Account, Source, or dataset.

Human sessions

Humans sign in through WorkOS/AuthKit. Browser sessions carry the verified user and organization. Account roles authorize product administration, while Source grants authorize data queries. Owners, Deployers, and Auditors therefore do not automatically gain data access from their role alone.

OAuth-capable MCP clients should connect to the MCP resource URL and follow the advertised metadata. Do not hardcode an authorization endpoint: a 401 response includes a WWW-Authenticate challenge whose resource_metadata value points to the protected-resource document.

Agent credentials

Create agents in Access. Depending on the WorkOS configuration, the flow uses Agent Registration or returns a one-time-visible organization API key. Store the credential in the runtime secret store as COMBINED_TOKEN. Combined retains a WorkOS reference and obfuscated display value, not a recoverable copy of the secret.

For REST and SDK requests, send:

Authorization: Bearer YOUR_TOKEN

MCP clients use the same bearer credential for unattended operation. The Account UUID remains an explicit MCP query parameter so copied configurations cannot silently change tenant scope.

Rotation and revocation

Credentials cannot be redisplayed. If a token is lost or exposed, revoke the agent and create a replacement. Revoking a credential, principal, membership, or grant increments the Account grant version; in-flight queries started under the old version are discarded before results return.

Status meanings

Never send provider credentials, Supabase keys, DuckLake paths, Desktop endpoint tokens, or service binding secrets to the public API. Connector authorization collects provider secrets through the narrow Source flow and stores them in the managed secret boundary.