API authentication#
Send a bearer credential on every API request:
Authorization: Bearer pat_...Keep bearer credentials server-side. A request never falls back to a browser cookie when its API credential is missing or invalid.
Personal access tokens#
A PAT begins with pat_. Supernova shows its secret once and stores only a hash. Create a replacement if the secret is lost; it cannot be recovered.
Each PAT belongs to one user and one organization, carries an explicit scope set, and records an optional expiry. Revocation takes effect on the next request.
OAuth access tokens#
OAuth uses authorization code with PKCE. The consent screen shows the organization and requested scopes. An access token must have the public API audience, a permitted issuer, a live jti, and the scope required by the endpoint.
The token subject becomes the caller principal. Idempotency and caller rate limits remain separate between principals even inside the same organization.
Inspect identity#
Returns the authenticated subject, organization, role, and granted scopes. Use it after login or profile selection to prove which tenant a credential addresses.
Returns organizations available to the authenticated user where the credential contract permits selection.
Scope vocabulary#
| Scope | Capability |
|---|---|
query:read or query:execute | Query and query-job resources during compatibility rollout |
data:read | Catalog, source reads, logs, and usage |
apps:manage | Source and PAT management |
models:read, models:write | Model resources |
files:write, files:admin | Data-repo changes |
members:manage | Organization membership |
data:policies:manage | Data policy administration |
An endpoint refuses a valid credential that lacks its required scope with 403 insufficient_scope.