Authentication

Every FaceMode session uses two credentials:

Credential	Format	Lifetime	Used for	Lives
API key	`fm_...`	Until revoked or `expiresAt`	All REST calls to `https://api.facemode.io/api`	Your backend only
Session `wsToken`	JWT string	15 minutes, single use	Ingestion WebSocket handshake	Your backend only

Both are secrets. Neither belongs in browser code, mobile apps, or logs.

REST API keys

Sending the key

Pass the key in the x-api-key header or in Authorization with the Bearer, ApiKey, or Api-Key scheme:

x-api-key: fm_your_key_here

Authorization: Bearer fm_your_key_here

Keys that do not start with fm_ are rejected. Only the key’s SHA-256 hash is stored - FaceMode never keeps the plaintext key.

Creating a key

Create keys in the FaceMode console, or programmatically with POST /api/keys (requires the keys:write scope):

curl -X POST "https://api.facemode.io/api/keys" \
  -H "x-api-key: $FACEMODE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "production-backend",
    "scopes": ["sessions:create", "sessions:read", "sessions:end", "avatars:read", "usage:read"],
    "expiresAt": "2027-01-01T00:00:00.000Z"
  }'

{
  "apiKey": {
    "id": "9a1b2c3d-...",
    "name": "production-backend",
    "key_prefix": "fm_ab12cd3",
    "scopes": ["sessions:create", "sessions:read", "sessions:end", "avatars:read", "usage:read"],
    "expires_at": "2027-01-01T00:00:00.000Z",
    "key": "fm_9f8e7d6c5b4a..."
  }
}

The raw key is returned exactly once, in apiKey.key. Store it immediately - it cannot be retrieved again. Up to 5 keys per account; expiresAt is optional (omit for no expiry).

Scopes

Each key carries a set of scopes. A call without the required scope fails with 403 and code AUTH_INSUFFICIENT_SCOPE.

Scope	Allows
`sessions:create`	Create sessions, reconnect (`POST /api/sessions`, `POST /api/sessions/:id/reconnect`)
`sessions:read`	Read session status (`GET /api/sessions`, `GET /api/sessions/:id`)
`sessions:end`	End, delete, and heartbeat sessions (`POST /:id/end`, `DELETE /:id`, `POST /:id/heartbeat`)
`avatars:read`	List and fetch avatars
`avatars:write`	Create, update, and delete custom avatars
`keys:read`	List API keys
`keys:write`	Create API keys
`keys:delete`	Delete API keys
`billing:read`	Read invoices and billing info
`billing:write`	Purchase credits (disabled during the beta - returns `403 BILLING_DISABLED`)
`credits:read`	Read your credit wallet (opt-in; never granted by default)
`usage:read`	Read usage metrics

Default scopes for a new key: sessions:create, sessions:read, sessions:end, avatars:read, usage:read. Request additional scopes at key creation; grant only what your backend needs.

Key errors

Status	Meaning
`401`	No API key was sent
`403`	Key is invalid, inactive, expired, or missing the required scope

Session WebSocket tokens

POST /api/sessions (and /reconnect) returns ingestion.wsToken - a signed JWT that authorizes exactly one WebSocket connection to the session’s ingestion endpoint.

Connecting

Send the token as a WebSocket subprotocol with the facemode. prefix:

const ws = new WebSocket(ingestion.url, [`facemode.${ingestion.wsToken}`]);

On the wire this becomes Sec-WebSocket-Protocol: facemode.<wsToken>; the server echoes the same subprotocol back on accept. Clients that cannot set subprotocols (some browsers, embedded SDKs) may pass the same JWT as a query parameter instead:

wss://<worker>/ws/<session_id>?token=<wsToken>

Only the facemode. subprotocol prefix is accepted. Other prefixes are rejected before the handshake completes.

Token rules

15-minute expiry. The JWT is signed with exp 15 minutes from issue.
Single use. A successful handshake consumes the token. Never reconnect with a consumed token - it will be rejected.
Fresh token on reconnect. POST /api/sessions/:id/reconnect returns a new ingestion.wsToken each call. Reconnect as many times as needed.
Scoped to one session. A token only opens the WebSocket URL issued with it; it cannot be reused across sessions.

Security rules

Keep the API key and wsToken on your server. The browser only ever receives the room URL and a separate viewer token you mint for that user - never the publisher roomToken FaceMode uses to publish.
Never log tokens. API keys, room tokens, wsToken JWTs, and the ?token= query string must be redacted in logs, error reports, and analytics.
Treat a wsToken like a password until it is consumed or expires: anyone holding it can open the session’s audio channel.
Rotate API keys if one may have leaked; revoke unused keys with DELETE /api/keys/:id (keys:delete scope).

Error envelope

Failed REST calls return a consistent shape:

{
  "error": { "code": "AUTH_INSUFFICIENT_SCOPE", "message": "Insufficient permissions for this action" },
  "message": "Insufficient permissions for this action"
}

Server-side failures arrive over the WebSocket as {"type": "error", "code": "...", "message": "...", "fatal": bool}. A fatal error closes the connection; reconnect with a fresh wsToken.

Get Started

Concepts

Integrations

REST API keys

Sending the key

Creating a key

Scopes

Key errors

Session WebSocket tokens

Connecting

Token rules

Security rules

Error envelope

​REST API keys

​Sending the key

​Creating a key

​Scopes

​Key errors

​Session WebSocket tokens

​Connecting

​Token rules

​Security rules

​Error envelope

REST API keys

Sending the key

Creating a key

Scopes

Key errors

Session WebSocket tokens

Connecting

Token rules

Security rules

Error envelope