Auth & API keys

Orchestate has two authentication surfaces: API keys authenticate programmatic access from the SDK and REST API, and a browser session authenticates the console and the Live Inspector WebSocket. This page explains both, plus how accounts and teams sign in.

API keys

API keys are the primary mechanism for authenticating against the HTTP API and the @orchestate/sdk client. Every key is scoped to a single organization, so a key can only read and write machines and instances that belong to its org.

Key format

A key is the prefix orch_ followed by 48 lowercase hex characters (24 random bytes), for example:

orch_3f9a2b1c8d4e5f60718293a4b5c6d7e8f90a1b2c3d4e5f60

Keys are generated in the console and the full secret is shown exactly once at creation time. Copy it immediately and store it somewhere safe — Orchestate keeps only a SHA-256 hash of the key, so the raw value can never be recovered or displayed again. If you lose a key, revoke it and create a new one.

For display purposes the console retains a 12-character prefix (e.g. orch_3f9a2b1) so you can identify a key in the list without exposing the secret.

Sending a key

Pass the key in the Authorization header using the Bearer scheme on every request to the REST API:

curl https://orchestate.wentzel.ai/api/machines \
  -H "Authorization: Bearer orch_YOUR_API_KEY"

The SDK takes the same key on its constructor and attaches the header for you on every call:

import { OrchestateClient } from '@orchestate/sdk';

const client = new OrchestateClient({
  apiKey: process.env.ORCHESTATE_API_KEY!,
});

const machines = await client.machines.list();

Note — requests without a valid Authorization: Bearer orch_… header are rejected with 401. The one exception is GET /api/health, which is an unauthenticated liveness probe.

Creating and revoking keys

Keys are managed entirely in the console:

Sign in to the console and open Settings → API Keys.
Click Create key, give it a descriptive name, and (optionally) set an expiry.
Copy the raw key from the one-time reveal dialog and store it securely.
To retire a key, click Revoke. Revocation takes effect immediately — subsequent requests with that key return 401.

Keys are org-scoped, can carry an optional expiry, and can be revoked at any time. An expired or revoked key is rejected the same way an unknown key is.

Security best practices

Note — treat API keys like passwords:

Store keys in environment variables (or a secrets manager), never in source code or client-side bundles.
Never commit a key to version control. If a key leaks, revoke it immediately and issue a replacement.
Rotate keys regularly and use the optional expiry to enforce a lifetime.
Use least privilege — issue separate keys per service or environment so you can revoke one without disrupting the others.

Account authentication (console sign-in)

The console itself is protected by an email-and-password account with optional social sign-in. These flows are how humans get into the dashboard; the API and SDK do not use them.

Email & password

Sign up with your name, email, and a password (minimum 8 characters).
Verify your email — a verification email is sent automatically on sign-up, and the account must be verified before it can sign in.
Log in with your verified email and password.
Reset your password — request a reset from the login screen and follow the link emailed to you.

Social sign-in

You can also sign in or sign up with GitHub or Google from the login and signup screens. Two-factor authentication is available on accounts for an extra layer of protection.

Teams and roles

Accounts belong to an organization, and members are assigned a role. The user who creates an org is its owner; the available roles are:

Role	Capabilities
owner	Full control, including billing and member management.
admin	Manage members, machines, and API keys.
editor	Publish machines and operate instances.
viewer	Read-only access to machines and instances.

API keys inherit the organization they are created in, not an individual member's role.

Session auth for the Live Inspector

The Live Inspector streams an instance's state transitions over a WebSocket at GET /api/inspect/{instanceId}. Unlike the REST API, the inspector is authenticated by your logged-in browser session cookie — not an API key.

For that reason, the SDK's client.instances.subscribe() helper is intended to run from an authenticated browser context, where the browser sends the session cookie automatically with the WebSocket upgrade (the SDK also appends a key parameter to the socket URL, but the server ignores it in favor of the session). It opens the inspector connection and invokes your callback with each { value, context } update, returning an unsubscribe function:

// Runs in an authenticated browser session, not server-to-server.
const unsubscribe = client.instances.subscribe(instanceId, (state) => {
  console.log(state.value, state.context);
});

// Later, to close the WebSocket:
unsubscribe();

Note —because the inspector relies on the session cookie, you cannot subscribe to it from a backend service using an API key. Use the REST endpoints (or the SDK's machines and instances methods) for server-to-server automation, and reserve the inspector for live, in-browser observation.