Authentication

The Platform API accepts two credentials, both sent as a bearer token in the Authorization header:

An API key (rk_...) is a long-lived secret. It works on every endpoint your key’s roles allow. Keep it on a server.
A session token is a short-lived JWT that you mint from an API key with POST /tokens. It works only on /sessions and /clips, and only for the models and sessions you name. Give it to a browser, a mobile app, or any client you do not control.

Server exchanges API key for a token, passes token to browser, browser connects to Reactor

API keys

Create an API key

Create keys in the Dashboard: click your user icon, then open API Keys. The full key appears only once, when you create it, so store it in a secret manager. Each key is bound to one account: the account that was selected when you created it. To create a key for a team, switch to the team first. See API keys and billing. A key acts with your roles in that account, or with a subset you choose when you create it. If you lose a role later, keys that relied on it lose it too.

You cannot create an API key with the Platform API using another API key or a session token. A credential that leaked cannot be used to create a replacement for itself. The reactor auth login command creates a key for the CLI through a browser sign-in; that key expires after 90 days.

Send an API key

curl https://api.reactor.inc/me \
  -H "Authorization: Bearer $REACTOR_API_KEY"

The API tells an API key from a JWT by its rk_ prefix. Older clients may send the key in a Reactor-API-Key header instead. The API reads that header only when there is no Authorization header. Do not use it in new code. Some endpoints accept only an API key: everything outside /sessions and /clips, including /me, /accounts, /models, /projects, POST /tokens, and POST /files.

Revoke an API key

Revoke keys in the Dashboard. A key can also revoke itself:

curl -X DELETE "https://api.reactor.inc/users/$USER_ID/api-keys/$API_KEY_ID" \
  -H "Authorization: Bearer $REACTOR_API_KEY"

$USER_ID is the id from GET /me. Revocation takes effect at once, and it also invalidates every session token minted from the key.

Treat an API key like a database password. Never put it in a browser, a mobile app, an edge worker, or source control. Rotate keys from time to time, and revoke a key as soon as you suspect it leaked.

Session tokens

A session token lets a client start sessions without holding your API key. It can call these endpoints and nothing else:

POST /sessions, to start a session on a model the token allows.
Every /sessions/{session_id}/... endpoint, for sessions the token created or was bound to. That covers reading and ending a session, WebRTC signaling, uploads, and step results.
GET /clips, for recordings of those sessions, also after a session ends.

Other endpoints reject session tokens with 403, except POST /tokens and POST /files. Those two endpoints return 401.

Mint a session token

Send your API key to POST /tokens. With no body, the token can start up to 5 sessions on any model your key may use, for 1 hour:

curl -X POST https://api.reactor.inc/tokens \
  -H "Authorization: Bearer $REACTOR_API_KEY" \
  -H "Reactor-API-Version: 1"

{
  "jwt": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_at": 1784375400,
  "authorization_details": [
    {
      "type": "session",
      "resources": { "models": { "all": true } },
      "constraints": {}
    }
  ]
}

The field is jwt, not token. expires_at is a Unix timestamp in seconds. An empty constraints object means the defaults apply, including the limit of 5 sessions.

Limit what a token can do

Before you hand a token to a client, limit it to what that client needs. Pass one authorization_details entry:

curl -X POST https://api.reactor.inc/tokens \
  -H "Authorization: Bearer $REACTOR_API_KEY" \
  -H "Reactor-API-Version: 1" \
  -H "Content-Type: application/json" \
  -d '{
    "expires_after": 900,
    "authorization_details": [
      {
        "type": "session",
        "resources": { "models": { "match": ["reactor/helios"] } },
        "constraints": { "max_sessions": 1, "max_session_duration_seconds": 600 }
      }
    ]
  }'

This token lives 15 minutes. It can start one session, only on reactor/helios, and that session ends after 10 minutes.

Field	Type	Description
`expires_after`	integer	Token lifetime in seconds. Defaults to 3600 (1 hour). The maximum is 6 hours, and a token never outlives the API key that minted it. Read `expires_at` in the response for the actual expiry.
`authorization_details`	array	Exactly one entry.
`authorization_details[].type`	string	Required. Always `"session"`.
`resources.models.match`	array of strings	The models the token may start sessions on, as `owner/name`. Use `owner/name:environment` to allow a non-production environment instead. Every model must be one your key can use. Set either `match` or `all`, not both.
`resources.models.all`	boolean	`true` allows every model your key can use.
`resources.sessions.bind`	array of UUIDs	Open sessions the token may act on although it did not create them. See Share a session.
`constraints.max_sessions`	integer	How many sessions the token may hold over its lifetime, from 1 to 500. Defaults to 5, or to the number of bound sessions. Ending a session does not free its slot.
`constraints.max_session_duration_seconds`	integer	Ends every session the token starts after this many seconds, from 1 to 86400. Omit it for no limit from the token. If your account also has a session time limit, the lower value applies.

The response repeats authorization_details in canonical form: model names are resolved, sorted, and deduplicated. It includes max_sessions when you supply a limit or bind sessions. Otherwise, it omits max_sessions, and the default limit of 5 sessions applies.

Use a session token

Send the token exactly as you would an API key:

curl -X POST https://api.reactor.inc/sessions \
  -H "Authorization: Bearer $REACTOR_JWT" \
  -H "Reactor-API-Version: 1" \
  -H "Content-Type: application/json" \
  -d '{"model": {"name": "reactor/helios"}}'

Each session the token starts is bound to it at once, so the same token can then negotiate transport, upload files, and end that session. A token can act only on the sessions it started. To let a second client join a session that already exists, mint a separate token for that client and bind the session to it:

{
  "authorization_details": [
    {
      "type": "session",
      "resources": {
        "models": { "match": ["reactor/helios"] },
        "sessions": { "bind": ["1f1e4b8e-1c2d-4f8a-9b6e-2a7c5d3e9f01"] }
      }
    }
  ]
}

Each bound session must be open and must belong to your key’s account and user.
Each bound session must run a model listed in resources.models.match.
Bound sessions count toward max_sessions. When you omit max_sessions, the limit equals the number of bound sessions, so the token cannot start new sessions. Set max_sessions higher to let it start more.

A session that is closed, belongs to someone else, or does not exist returns 403. The three cases look the same, so the endpoint never reveals whether a session ID exists.

Errors

Status	When
`400`	The body is malformed, a field inside `authorization_details` is unknown, or a value is out of range.
`401`	The API key is missing, invalid, revoked, or expired. A session token instead of an API key also returns `401`: a token cannot mint a token.
`403`	Your key cannot use a listed model, cannot bind a listed session, or has no roles left that allow sessions.
`426`	`Reactor-API-Version` is older than the server supports.
`503`	Token issuance is temporarily unavailable. Retry with backoff.

A session token that has expired, or whose API key was revoked, returns 401 on every call. A session token used outside its limits returns 403: another session, a model it does not allow, or a new session beyond max_sessions. Other endpoints reject session tokens with 403, except POST /tokens and POST /files, which return 401.

Accounts and roles

Every request acts in one account: the account the API key is bound to. Session tokens inherit it. To act in another account, use a key created in that account. What a credential may do depends on its roles in that account:

Role	Can
`developer`	Start sessions, read the account’s sessions and usage, and manage the account’s models
`account_admin`	Everything a developer can, plus manage members, invitations, and model access grants
`billing_admin`	Read the account and its members, and manage billing in the Dashboard

Each endpoint page names the roles it needs. A credential without them gets 403.

Next steps

Mint a session token

The full POST /tokens reference, with a playground.

Client authentication

Mint tokens from a server and hand them to the JavaScript, Python, and mobile SDKs.

Get started

SDK Reference

CLI Reference

Platform API Reference

Endpoints

API keys

Create an API key

Send an API key

Revoke an API key

Session tokens

Mint a session token

Limit what a token can do

Use a session token

Errors

Accounts and roles

Next steps

Mint a session token

Client authentication

​API keys

​Create an API key

​Send an API key

​Revoke an API key

​Session tokens

​Mint a session token

​Limit what a token can do

​Use a session token

​Share a session with another client

​Errors

​Accounts and roles

​Next steps

Mint a session token

Client authentication

API keys

Create an API key

Send an API key

Revoke an API key

Session tokens

Mint a session token

Limit what a token can do

Use a session token

Share a session with another client

Errors

Accounts and roles

Next steps