Mint a fresh short-lived client token (canonical V0)

Canonical V0 token-refresh endpoint (Decision D1). Mints a new short-lived (5-minute) HMAC-signed client_token for an existing session. Use this for reconnects, delayed connections, or browser sleep recovery.

Requires normal /v1/ API-key authentication. The deployed Worker also exposes this operation at /v1/sessions/{session_id}/ws-token; that path is a bridge/internal alias only. New integrations MUST use /client-token.

POST/v1/sessions/{session_id}/client-token

Authorization

AuthorizationBearer token · headerrequired

`Authorization: Bearer <api_key>`

x-api-keyAPI key · headerrequired

`x-api-key: <api_key>`

Path parameters

session_idstringrequired

min length 1 · matches ^session:[A-Za-z0-9_-]+$

Responses

200Fresh short-lived client token minted.

client_tokenstringrequired

Freshly-minted short-lived (5-minute) client token.

min length 1

expires_atinteger<int64>required

Unix epoch milliseconds when the new `client_token` expires.

min 0

stream_metadataobjectrequired

Media-plane connection metadata.

Show properties

ice_serversobject[]required

ICE servers the browser should use when negotiating a WebRTC transport. May be empty for `websocket_fmp4` sessions.

Show properties

Array of object

credentialstring

TURN credential (only for `turn:` servers).

urlsstring<uri> | string<uri>[]required

STUN/TURN URL or list of URLs (per RFC 7065). Example: `stun:stun.l.google.com:19302`.

Show properties

Any of:

string<uri>

string<uri>

string<uri>[]

Array of string<uri>

string<uri>

usernamestring

TURN username (only for `turn:` servers).

session_tokenstringrequired

Purpose-scoped session token used to authorize media-plane connections (WebSocket or SFU subscriber). Distinct from the API key.

min length 1

sfu_endpointstring<uri> | nullrequired

Cloudflare Realtime SFU publisher endpoint. `null` when the session is using the `websocket_fmp4` transport.

transportstringrequired

Transport preference for this session. `auto` — server picks (prefers SFU when configured, falls back to fMP4). `webrtc_sfu` — Cloudflare Realtime SFU (WebRTC); fails closed if the SFU prerequisites are missing, does NOT fall back to fMP4. `websocket_fmp4` — fMP4 over WebSocket (compatibility transport).

Allowed:autowebrtc_sfuwebsocket_fmp4

401API key missing or invalid.

Any of:

object

codestringrequired

Allowed:AVTR_PROVIDER_DOWNSTREAM_FAILEDAVTR_PROVIDER_TIMEOUTAVTR_PROVIDER_UNAVAILABLEAVTR_RATE_LIMIT_CONCURRENT_SESSIONSAVTR_RATE_LIMIT_EXCEEDEDAVTR_RATE_LIMIT_PROVIDER_QUOTAAVTR_RENDER_CAPACITYAVTR_RENDER_TIMEOUTAVTR_SESSION_STATE_UNAVAILABLEAVTR_SFU_CONNECTION_FAILEDAVTR_SFU_NEGOTIATION_FAILEDAVTR_SFU_ROOM_FULL

doc_urlstring<uri>required

Absolute HTTPS URL to human-facing documentation for this error code.

matches ^https:\/\/

messagestringrequired

Human-readable, provider-agnostic error message. MUST NOT contain provider names, model ids, infrastructure identifiers (Modal/D1/DO), IP addresses, stack traces, or API keys. Consumers MAY localize.

min length 1

request_idstring<uuid>required

Per-request correlation UUID. Echoes the `X-Request-Id` response header. Used to locate traces and logs.

retry_afterintegerrequired

Seconds the client SHOULD wait before retrying (1..3600). REQUIRED for retryable codes; FORBIDDEN for non-retryable codes. Clients SHOULD honor this value and SHOULD apply jitter.

min 1 · max 3600

object

codestringrequired

Allowed:AVTR_AUTH_EXPIRED_TOKENAVTR_AUTH_FORBIDDENAVTR_AUTH_INVALID_KEYAVTR_AUTH_MISSING_CREDENTIALSAVTR_AUTH_MISSING_SCOPEAVTR_PROVIDER_MISCONFIGUREDAVTR_RENDER_FAILEDAVTR_RENDER_MISCONFIGUREDAVTR_SESSION_CANCELLEDAVTR_SESSION_CONFLICTAVTR_SESSION_ENDEDAVTR_SESSION_NOT_FOUNDAVTR_SFU_NOT_CONFIGURED

doc_urlstring<uri>required

Absolute HTTPS URL to human-facing documentation for this error code.

matches ^https:\/\/

messagestringrequired

Human-readable, provider-agnostic error message. MUST NOT contain provider names, model ids, infrastructure identifiers (Modal/D1/DO), IP addresses, stack traces, or API keys. Consumers MAY localize.

min length 1

request_idstring<uuid>required

Per-request correlation UUID. Echoes the `X-Request-Id` response header. Used to locate traces and logs.

403Missing `sessions:write` scope.

Any of:

object

codestringrequired

doc_urlstring<uri>required

Absolute HTTPS URL to human-facing documentation for this error code.

matches ^https:\/\/

messagestringrequired

Human-readable, provider-agnostic error message. MUST NOT contain provider names, model ids, infrastructure identifiers (Modal/D1/DO), IP addresses, stack traces, or API keys. Consumers MAY localize.

min length 1

request_idstring<uuid>required

Per-request correlation UUID. Echoes the `X-Request-Id` response header. Used to locate traces and logs.

retry_afterintegerrequired

Seconds the client SHOULD wait before retrying (1..3600). REQUIRED for retryable codes; FORBIDDEN for non-retryable codes. Clients SHOULD honor this value and SHOULD apply jitter.

min 1 · max 3600

object

codestringrequired

doc_urlstring<uri>required

Absolute HTTPS URL to human-facing documentation for this error code.

matches ^https:\/\/

messagestringrequired

Human-readable, provider-agnostic error message. MUST NOT contain provider names, model ids, infrastructure identifiers (Modal/D1/DO), IP addresses, stack traces, or API keys. Consumers MAY localize.

min length 1

request_idstring<uuid>required

Per-request correlation UUID. Echoes the `X-Request-Id` response header. Used to locate traces and logs.

404Session not found, or cross-tenant access denied.

Any of:

object

codestringrequired

doc_urlstring<uri>required

Absolute HTTPS URL to human-facing documentation for this error code.

matches ^https:\/\/

messagestringrequired

Human-readable, provider-agnostic error message. MUST NOT contain provider names, model ids, infrastructure identifiers (Modal/D1/DO), IP addresses, stack traces, or API keys. Consumers MAY localize.

min length 1

request_idstring<uuid>required

Per-request correlation UUID. Echoes the `X-Request-Id` response header. Used to locate traces and logs.

retry_afterintegerrequired

Seconds the client SHOULD wait before retrying (1..3600). REQUIRED for retryable codes; FORBIDDEN for non-retryable codes. Clients SHOULD honor this value and SHOULD apply jitter.

min 1 · max 3600

object

codestringrequired

doc_urlstring<uri>required

Absolute HTTPS URL to human-facing documentation for this error code.

matches ^https:\/\/

messagestringrequired

Human-readable, provider-agnostic error message. MUST NOT contain provider names, model ids, infrastructure identifiers (Modal/D1/DO), IP addresses, stack traces, or API keys. Consumers MAY localize.

min length 1

request_idstring<uuid>required

Per-request correlation UUID. Echoes the `X-Request-Id` response header. Used to locate traces and logs.

429Rate limit exceeded.

Any of:

object

codestringrequired

doc_urlstring<uri>required

Absolute HTTPS URL to human-facing documentation for this error code.

matches ^https:\/\/

messagestringrequired

Human-readable, provider-agnostic error message. MUST NOT contain provider names, model ids, infrastructure identifiers (Modal/D1/DO), IP addresses, stack traces, or API keys. Consumers MAY localize.

min length 1

request_idstring<uuid>required

Per-request correlation UUID. Echoes the `X-Request-Id` response header. Used to locate traces and logs.

retry_afterintegerrequired

Seconds the client SHOULD wait before retrying (1..3600). REQUIRED for retryable codes; FORBIDDEN for non-retryable codes. Clients SHOULD honor this value and SHOULD apply jitter.

min 1 · max 3600

object

codestringrequired

doc_urlstring<uri>required

Absolute HTTPS URL to human-facing documentation for this error code.

matches ^https:\/\/

messagestringrequired

Human-readable, provider-agnostic error message. MUST NOT contain provider names, model ids, infrastructure identifiers (Modal/D1/DO), IP addresses, stack traces, or API keys. Consumers MAY localize.

min length 1

request_idstring<uuid>required

Per-request correlation UUID. Echoes the `X-Request-Id` response header. Used to locate traces and logs.

503Token secret not configured, or session state unavailable.

Any of:

object

codestringrequired

doc_urlstring<uri>required

Absolute HTTPS URL to human-facing documentation for this error code.

matches ^https:\/\/

messagestringrequired

Human-readable, provider-agnostic error message. MUST NOT contain provider names, model ids, infrastructure identifiers (Modal/D1/DO), IP addresses, stack traces, or API keys. Consumers MAY localize.

min length 1

request_idstring<uuid>required

Per-request correlation UUID. Echoes the `X-Request-Id` response header. Used to locate traces and logs.

retry_afterintegerrequired

Seconds the client SHOULD wait before retrying (1..3600). REQUIRED for retryable codes; FORBIDDEN for non-retryable codes. Clients SHOULD honor this value and SHOULD apply jitter.

min 1 · max 3600

object

codestringrequired

doc_urlstring<uri>required

Absolute HTTPS URL to human-facing documentation for this error code.

matches ^https:\/\/

messagestringrequired

Human-readable, provider-agnostic error message. MUST NOT contain provider names, model ids, infrastructure identifiers (Modal/D1/DO), IP addresses, stack traces, or API keys. Consumers MAY localize.

min length 1

request_idstring<uuid>required

Per-request correlation UUID. Echoes the `X-Request-Id` response header. Used to locate traces and logs.

Try it

Server

Base URLCustom base URLOverrides the selected server when set.

Authorization

Bearer tokenRemember on this deviceInclude my values in samples

Parameters

session_idpath*

Request

curl -X POST "https://api.avtr.internal/v1/v1/sessions/session%3A02732348-1350-413a-9f0c-d6f47210b417/client-token" \
  -H "Authorization: Bearer YOUR_TOKEN"

const response = await fetch("https://api.avtr.internal/v1/v1/sessions/session%3A02732348-1350-413a-9f0c-d6f47210b417/client-token", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN"
  }
});

import requests

response = requests.post(
    "https://api.avtr.internal/v1/v1/sessions/session%3A02732348-1350-413a-9f0c-d6f47210b417/client-token",
    headers={
        "Authorization": "Bearer YOUR_TOKEN"
    },
)

Response

{
  "client_token": "string",
  "expires_at": 0,
  "stream_metadata": {
    "ice_servers": [
      {
        "credential": "string",
        "urls": "http://example.com",
        "username": "string"
      }
    ],
    "session_token": "string",
    "sfu_endpoint": "http://example.com"
  },
  "transport": "auto"
}

{
  "code": "AVTR_PROVIDER_DOWNSTREAM_FAILED",
  "doc_url": "http://example.com",
  "message": "string",
  "request_id": "266ea41d-adf5-480b-af50-15b940c2b846",
  "retry_after": 1
}

{
  "code": "AVTR_PROVIDER_DOWNSTREAM_FAILED",
  "doc_url": "http://example.com",
  "message": "string",
  "request_id": "266ea41d-adf5-480b-af50-15b940c2b846",
  "retry_after": 1
}

{
  "code": "AVTR_PROVIDER_DOWNSTREAM_FAILED",
  "doc_url": "http://example.com",
  "message": "string",
  "request_id": "266ea41d-adf5-480b-af50-15b940c2b846",
  "retry_after": 1
}

{
  "code": "AVTR_PROVIDER_DOWNSTREAM_FAILED",
  "doc_url": "http://example.com",
  "message": "string",
  "request_id": "266ea41d-adf5-480b-af50-15b940c2b846",
  "retry_after": 1
}

{
  "code": "AVTR_PROVIDER_DOWNSTREAM_FAILED",
  "doc_url": "http://example.com",
  "message": "string",
  "request_id": "266ea41d-adf5-480b-af50-15b940c2b846",
  "retry_after": 1
}