Authentication

Reactor uses API keys to authenticate requests. JavaScript apps exchange the key for a short-lived token; Python apps pass the key directly and the SDK does the exchange for them.

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

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 },
      },
    ],
  }),
});
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 three 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.

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>
  );
}

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 that can access the session. Session-scoped tokens are bound to the sessions they create, so the simplest approach is to hand the client the same scoped JWT your backend created the session with. See 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. See Sessions.

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

Get Started

Concepts

SDK Reference

Resources

Get your API key

JavaScript

How it works

Generate a session-scoped token

Server-side proxy

Tokens for a queue or admission-control server

Python

How it works

Minting a token yourself

​Get your API key

​JavaScript

​How it works

​Generate a session-scoped token

​Server-side proxy

​Tokens for a queue or admission-control server

​Python

​How it works

​Minting a token yourself

Get your API key

JavaScript

How it works

Generate a session-scoped token

Server-side proxy

Tokens for a queue or admission-control server

Python

How it works

Minting a token yourself