Authentication

Reactor uses API keys to authenticate requests. JavaScript apps exchange the key for a short-lived token on their server; Python apps pass the key directly and the SDK does the exchange for them. Java apps exchange it explicitly with Reactor.fetchJwt, or use a token supplied by their backend.

Get your API key

Create an account

Create an API key

Open the Dashboard, click your user icon, then navigate to API Keys to create a new key.

Copy your key

Your key starts with rk_. Store it securely and never commit it to source control.

JavaScript
Python
C++
Swift
Java

JavaScript

How it works

Your server exchanges the API key for a short-lived token, which the browser uses to connect. Always mint session-scoped tokens: pass authorization_details naming the models the token may start sessions for. A scoped token can only create and operate its own sessions — it cannot touch other sessions, other models, or any account API. If it leaks, the blast radius is a handful of sessions on the models you listed, for at most the token’s lifetime (1 hour by default).

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

Generate a session-scoped token

Exchange your API key for a short-lived token by making a POST request to the /tokens endpoint with your API key in the Reactor-API-Key header. Always scope the token with authorization_details, naming the models it may start sessions for:

Session-scoped (1-hour expiry)

const result = await fetch("https://api.reactor.inc/tokens", {
  method: "POST",
  headers: {
    "Reactor-API-Key": process.env.REACTOR_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    authorization_details: [
      {
        type: "session",
        resources: { models: { match: ["your-model-name"] } },
        constraints: { max_sessions: 5, max_session_duration_seconds: 3600 },
      },
    ],
  }),
});
const { jwt, expires_at } = await result.json();

Custom expiry

const result = await fetch("https://api.reactor.inc/tokens", {
  method: "POST",
  headers: {
    "Reactor-API-Key": process.env.REACTOR_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    expires_after: Number(process.env.TOKEN_LIFETIME_SECONDS),
    authorization_details: [
      {
        type: "session",
        resources: { models: { match: ["your-model-name"] } },
        constraints: { max_sessions: 5 },
      },
    ],
  }),
});
const { jwt, expires_at } = await result.json();

The authorization_details entry has these parts:

type: "session" (required) — the only supported type today. The token can create sessions and do everything those sessions need (transport negotiation, uploads, clips, session logs), and nothing else.
resources.models.match (required) — a non-empty list of models the token may start sessions for. Every listed model must be visible to your API key. There is no wildcard; list each model explicitly.
constraints.max_sessions (optional) — how many sessions the token may create in total, from 1 to 500. Defaults to 5. This counts sessions ever created by the token, not concurrent ones: closing a session does not restore capacity.
constraints.max_session_duration_seconds (optional) — cap every session the token creates at this many seconds, from 1 to 86 400 (24 hours). Omit for no limit; if the account also has a maximum, the lower value wins. See Rate limits.
resources.sessions.bind (optional) — a non-empty list of IDs of open sessions that the token did not create itself. Required when the token must act on such a session. See Acting on a session another token created.

Session-scoped tokens live for 1 hour by default. Pass expires_after (in seconds) to shorten or extend the lifetime, up to the server ceiling of 6 hours; values at or above the ceiling are silently clamped. The server still returns 200, so always check expires_at (a Unix epoch timestamp) on the response to confirm the actual expiry.

Omitting authorization_details mints an unscoped token that can call every API your key’s roles allow — sessions on any model, account data, key management. Never hand an unscoped token to a browser. Reserve unscoped tokens for trusted server-to-server calls (for example the Platform API), and don’t store your API key in client-side code either: use your server as a proxy to mint scoped tokens, as shown below.

Server-side proxy

Set up an API route on your server that mints a session-scoped token and returns it to your frontend:

import { NextResponse } from "next/server";

export async function POST() {
  const result = await fetch("https://api.reactor.inc/tokens", {
    method: "POST",
    headers: {
      "Reactor-API-Key": process.env.REACTOR_API_KEY!,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      authorization_details: [
        {
          type: "session",
          resources: { models: { match: ["your-model-name"] } },
        },
      ],
    }),
  });
  const { jwt } = await result.json();

  return NextResponse.json({ jwt });
}

app.post("/api/token", async (_req, res) => {
  const result = await fetch("https://api.reactor.inc/tokens", {
    method: "POST",
    headers: {
      "Reactor-API-Key": process.env.REACTOR_API_KEY!,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      authorization_details: [
        {
          type: "session",
          resources: { models: { match: ["your-model-name"] } },
        },
      ],
    }),
  });
  const { jwt } = await result.json();

  res.json({ jwt });
});

Then fetch the token from your frontend and pass it to the SDK:

app/page.tsx

"use client";

import { use } from "react";
import { ReactorProvider, ReactorView } from "@reactor-team/js-sdk";

async function getToken() {
  const result = await fetch("/api/token", { method: "POST" });
  const { jwt } = await result.json();
  return jwt;
}

const tokenPromise = getToken();

export default function App() {
  const token = use(tokenPromise);
  return (
    <ReactorProvider modelName="your-model-name" jwtToken={token}>
      <ReactorView className="w-full aspect-video" />
    </ReactorProvider>
  );
}

Acting on a session another token created

A session-scoped token can act on the sessions in its bound set: the sessions it created, plus any named in resources.sessions.bind when it was minted. Requests on a session outside that set return 403, including DELETE /sessions/{id}. To act on a session that a different token created, mint a token with bind naming that session, then use it:

async function mintBoundToken(sessionId: string) {
  const result = await fetch("https://api.reactor.inc/tokens", {
    method: "POST",
    headers: {
      "Reactor-API-Key": process.env.REACTOR_API_KEY!,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      authorization_details: [
        {
          type: "session",
          resources: {
            models: { match: ["your-model-name"] },
            sessions: { bind: [sessionId] },
          },
        },
      ],
    }),
  });
  const { jwt } = await result.json();
  return jwt;
}

// The DELETE succeeds only because the token was minted with this session in `bind`.
async function endSession(sessionId: string) {
  const boundJwt = await mintBoundToken(sessionId);
  const result = await fetch(`https://api.reactor.inc/sessions/${sessionId}`, {
    method: "DELETE",
    headers: { Authorization: `Bearer ${boundJwt}` },
  });
  if (!result.ok) throw new Error(`Could not end session ${sessionId}: ${result.status}`);
}

The response from /tokens echoes authorization_details with the bound set and the resolved max_sessions. Bound IDs are stored on the server and do not appear in the JWT claims.Rules for bind:

Every ID in bind must name a session that is still open and that your account owns. A closed, foreign, or unknown ID returns the same 403, so the endpoint cannot be used to find session IDs.
The model of each bound session must appear in models.match. If it does not, the request returns 403.
max_sessions defaults to the number of bound sessions, so the token has no room left to create: it can operate the sessions it was given, but POST /sessions returns 403. Pass a larger max_sessions when the token also has to create sessions.

Ending a session you did not create

The JavaScript SDK deletes a session only from the client that created it (see Who owns the session). To end it from any other client or server, send DELETE /sessions/{id} with a token bound to that session as the bearer, as endSession above does. The JSON body with a reason is optional.A server process that holds the API key does not need a token. It can send the key itself as the bearer on DELETE /sessions/{id} and end any session under your account. Never do this from a front end. The API key must stay on your server.

Keeping the token fresh for a whole session

jwtToken also accepts a resolver — a function returning a string or a Promise<string> — instead of a static value. Pass one whenever a session might outlive a single connect: the SDK calls the resolver again for every later request that session makes (uploads, clip manifests, ICE refreshes, SDP renegotiation), not just the initial connect.A resolver that mints a fresh token on every call breaks the session the moment it runs: a session-scoped token can only act on the sessions it created, so a newly-minted token has none of them bound yet, and the next upload or clip request 403s. Cache the token yourself, and only mint again once it’s close to expiring:

const TOKEN_REFRESH_SKEW_MS = 60_000;
let cachedToken: { jwt: string; expiresAtMs: number } | null = null;
let inflightToken: Promise<string> | null = null;

async function getToken(): Promise<string> {
  if (cachedToken && Date.now() < cachedToken.expiresAtMs - TOKEN_REFRESH_SKEW_MS) {
    return cachedToken.jwt;
  }
  if (inflightToken) return inflightToken; // coalesce parallel hops
  inflightToken = (async () => {
    try {
      const result = await fetch("/api/token", { method: "POST", cache: "no-store" });
      const { jwt, expires_at } = await result.json();
      cachedToken = { jwt, expiresAtMs: expires_at * 1000 };
      return jwt;
    } finally {
      inflightToken = null;
    }
  })();
  return inflightToken;
}

Cache the token in your own code, not in the browser’s HTTP cache: fetch with { cache: "no-store" } rather than relying on a Cache-Control header to do the memoizing for you. The browser cache is outside your control — DevTools’ “Disable cache”, an eviction, or a shared proxy can all miss it silently, and the resolver falls back to minting a token with no sessions bound, 403ing every call the session makes from then on.

Edge case: a session created moments before the cached token expires is orphaned at the next refresh, because the freshly minted token is not bound to it. Re-mint with resources.sessions.bind naming that session, as shown in Acting on a session another token created.

Tokens for a queue or admission-control server

If you run an admission-control layer in front of a fixed pool of sessions — a waiting room gating limited GPU capacity, for example — mint a separate token per admitted slot instead of one shared token for the whole pool. Scope each token to max_sessions: 1 so it can create exactly the one session it is being admitted into:

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

async function mintSlotToken(model: string, slotLifetimeSeconds: number) {
  const result = await fetch("https://api.reactor.inc/tokens", {
    method: "POST",
    headers: {
      "Reactor-API-Key": process.env.REACTOR_API_KEY!,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      expires_after: slotLifetimeSeconds,
      authorization_details: [
        {
          type: "session",
          resources: { models: { match: [model] } },
          constraints: { max_sessions: 1 },
        },
      ],
    }),
  });
  const { jwt, expires_at } = await result.json();
  return { jwt, expires_at };
}

Size slotLifetimeSeconds to the slot’s whole lifetime: the time an admitted user might take to connect, plus the full session duration. Omitting it defaults to 1 hour, and 6 hours is the ceiling; a session-scoped token can’t be topped up mid-session, so undersizing this strands the session it created. Hand the resulting jwt to the admitted client the same way as the server-side proxy above; its connect() call creates the session and binds it to this token’s grant.

If your API key is compromised, rotate it immediately from the Dashboard. Rotating does not affect active sessions. Need help? Email us at support@reactor.inc.

Adopting an existing session. If your backend creates a session and hands the sessionId to a client, that client must connect with a token bound to the session. See Acting on a session another token created and Sessions.

Python

How it works

Python runs server-side, so you pass your API key straight to the Reactor constructor. On connect(), the SDK exchanges it for a short-lived, session-scoped token — scoped to the model you built the Reactor with — and authenticates every request with that token, never the raw key. If that token leaks, the blast radius is a handful of sessions on that one model, not your whole account. Scoping is automatic; there is nothing extra to configure.

Your app sends the API key directly to Reactor

Pass your API key directly to the Reactor constructor:

import os
from reactor_sdk import Reactor

reactor = Reactor(
    model_name="your-model-name",
    api_key=os.environ["REACTOR_API_KEY"],
)

# Mints a token scoped to "your-model-name", then connects with it.
await reactor.connect()

Never hardcode rk_... values in your code or commit them to source control. Use environment variables.

Minting a token yourself

Need a token for something other than a Reactor connection — a JWT broker that hands tokens to browser clients, for instance? Call fetch_jwt and scope it with models:

import asyncio
import os
from reactor_sdk import DEFAULT_API_URL, fetch_jwt

# fetch_jwt is synchronous — run it in a thread from async code so it doesn't
# block the event loop.
jwt = await asyncio.to_thread(
    fetch_jwt,
    api_key=os.environ["REACTOR_API_KEY"],
    api_url=DEFAULT_API_URL,
    models=["your-model-name"],  # session-scoped to these models
)

Pass max_sessions to cap how many sessions the token may create (1–500, default 5), and expires_after (in seconds) to shorten its lifetime below the 6-hour ceiling. Omitting models mints an unscoped token that can call every API your key’s roles allow — reserve that for trusted server-to-server calls such as the Platform API, and never hand one to a client.

Adopting a session someone else created. connect(session_id=...) attaches to a session that already exists rather than creating one. Because a session-scoped token can only act on the sessions it created itself, the SDK mints an unscoped token for this path, and fetch_jwt has no bind argument. A Python process holds the API key, so it can send DELETE /sessions/{id} with the key as the bearer to end any session. See Acting on a session another token created under the JavaScript tab, and Sessions.

Need help? Email us at support@reactor.inc.

C++

How it works

C++ runs natively — a desktop client, an engine, a capture pipeline — so you pass your API key straight to the Reactor constructor for a trusted environment, or a JWT minted elsewhere for anything else. With an ApiKey, connect() exchanges it for a short-lived, session-scoped token — scoped to the model you built the client with — and authenticates every request with that token, never the raw key. If that token leaks, the blast radius is a handful of sessions on that one model, not your whole account. Scoping is automatic; there is nothing extra to configure.Pass your API key directly to the Reactor constructor:

#include <reactor/reactor.hpp>

reactor::Reactor client{"your-model-name", reactor::ApiKey{std::getenv("REACTOR_API_KEY")}};

// Mints a token scoped to "your-model-name", then connects with it.
client.connect().get();

Never hardcode rk_... values in your code or commit them to source control. Use environment variables.

Using a token minted elsewhere

For a client that should never hold the raw API key — a game client, a desktop app distributed to end users — construct with a Jwt instead, minted by your server the same way the server-side proxy above does for the browser SDK:

reactor::Reactor client{"your-model-name", reactor::Jwt{token_from_your_backend}};
client.connect().get();

Adopting a session someone else created. connect() takes a ConnectOptions with a session_id, to attach to a session that already exists rather than creating one. The token you connect with must be bound to the session. See Acting on a session another token created under the JavaScript tab, and Sessions.

Need help? Email us at support@reactor.inc.

Swift

How it works

Swift runs natively — a macOS or iOS app — so you pass your API key straight to the Reactor initializer for a trusted environment, or a JWT minted elsewhere for anything else. With an API key, the async initializer exchanges it for a short-lived, session-scoped token — scoped to the model you built the client with — and authenticates every request with that token, never the raw key. If that token leaks, the blast radius is a handful of sessions on that one model, not your whole account. Scoping is automatic; there is nothing extra to configure.Pass your API key directly to the Reactor initializer:

import Reactor

let reactor = try await Reactor(model: "your-model-name", apiKey: apiKey)
// Mints a token scoped to "your-model-name", then creates the client with it.

Never hardcode rk_... values in your code or commit them to source control. Use environment variables, or an Xcode scheme’s environment for local development.

Using a token minted elsewhere

For a client that should never hold the raw API key — an iOS app distributed to end users — construct with jwt: instead, minted by your server the same way the server-side proxy above does for the browser SDK:

let reactor = try Reactor(model: "your-model-name", jwt: tokenFromYourBackend)
try await reactor.connect()

Adopting a session someone else created. connect(sessionID:connectionID:) takes a sessionID to attach to a session that already exists rather than creating one. The token you connect with must be bound to the session. See Acting on a session another token created under the JavaScript tab, and Sessions.

Need help? Email us at support@reactor.inc.

Java

On a trusted server

The Java SDK accepts a JWT through ReactorOptions. Use Reactor.fetchJwt to exchange an API key before creating the client. Scope the token to the model your application uses:

import inc.reactor.sdk.*;

String apiUrl = "https://api.reactor.inc";
JsonValue scope = JsonValue.parse("""
    {
      "models": ["reactor/helios"],
      "max_sessions": 1,
      "max_session_duration_seconds": 3600,
      "expires_after": 3600
    }
    """);
String jwt = Reactor.fetchJwt(apiUrl, System.getenv("REACTOR_API_KEY"), scope, false).join();

try (Reactor reactor = Reactor.open(ReactorOptions
        .builder(apiUrl, "reactor/helios").jwt(jwt).build())) {
    try {
        reactor.connect().join();
        // Send commands and receive frames here.
    } finally {
        reactor.disconnect().join();
    }
}

The models option makes the token session-scoped. The other options limit how many sessions it can create, each session’s duration, and the token’s lifetime. The final false keeps local-development mode disabled.

Reactor.fetchJwt(apiUrl, apiKey) without scoping options returns a token with the API key’s permissions. It does not automatically restrict the token to a model. Do not hand an unscoped token or the API key to a distributed app.

In a distributed application

Mint a session-scoped JWT on your backend, then pass that token to the Java client:

ReactorOptions options = ReactorOptions.builder("https://api.reactor.inc", "reactor/helios")
        .jwt(tokenFromYourBackend)
        .build();

try (Reactor reactor = Reactor.open(options)) {
    try {
        reactor.connect().join();
        // Send commands and receive frames here.
    } finally {
        reactor.disconnect().join();
    }
}

Keep the API key on your backend. When attaching to an existing session with connect(sessionId, connectionId), use a token authorized for that session.See Java installation for the JDK and native-access requirements, and Reactor for connection and cleanup methods.

Get Started

Concepts

SDK Reference

Resources

Get your API key

JavaScript

How it works

Generate a session-scoped token

Server-side proxy

Acting on a session another token created

Ending a session you did not create

Keeping the token fresh for a whole session

Tokens for a queue or admission-control server

Python

How it works

Minting a token yourself

C++

How it works

Using a token minted elsewhere

Swift

How it works

Using a token minted elsewhere

Java

On a trusted server

In a distributed application

​Get your API key

​JavaScript

​How it works

​Generate a session-scoped token

​Server-side proxy

​Acting on a session another token created

​Ending a session you did not create

​Keeping the token fresh for a whole session

​Tokens for a queue or admission-control server

​Python

​How it works

​Minting a token yourself

​C++

​How it works

​Using a token minted elsewhere

​Swift

​How it works

​Using a token minted elsewhere

​Java

​On a trusted server

​In a distributed application

Get your API key

JavaScript

How it works

Generate a session-scoped token

Server-side proxy

Acting on a session another token created

Ending a session you did not create

Keeping the token fresh for a whole session

Tokens for a queue or admission-control server

Python

How it works

Minting a token yourself

C++

How it works

Using a token minted elsewhere

Swift

How it works

Using a token minted elsewhere

Java

On a trusted server

In a distributed application