---
title: API authentication
description: Authenticate with a scoped personal access token or OAuth bearer and understand organization identity and revocation.
species: reference
---
# API authentication

Send a bearer credential on every API request:

```bash fragment
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

```endpoint
GET /whoami
```

Returns the authenticated subject, organization, role, and granted scopes. Use it after login or profile selection to prove which tenant a credential addresses.

```endpoint
GET /orgs
```

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`.