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.
Service keys#
A service key begins with nsk_ and belongs to the organization rather than to
a person — use one for a job, a script, or anything that keeps running when its
author leaves.
Authorization: Bearer nsk_...An organization admin creates a key under Settings → Query access, names it,
and copies the secret; like a PAT it is shown once and stored only as a hash.
Revoking a key takes effect on the next request.
A key is read-only and carries exactly query:read and data:read — it can run
queries and read the catalog, and nothing widens that. A key reads only the
tables it was granted; see Queries for what a refusal looks
like.
Keys work once the organization has table permissions turned on, since those
grants are what decide the tables a key may read. Until then a valid key is
refused with 403 service_key_permissions_off.
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.