RTC token API

Authentication

HTTP Basic over TLS: user name is the App ID, password is the App Secret of the same credential. The same endpoints are available on api.fahswertc.com and token.fahswertc.com.

Every authentication failure returns the same 401 response, whether the App ID is unknown, the secret is wrong or the credential was revoked.

• Rotating a secret in the console invalidates the old secret immediately.
• A credential may carry an IP allowlist; requests from other addresses get 403 ip_not_allowed.
• Console session tokens are not accepted on these endpoints.

POST /v1/rtc/tokens

• room_id (string, required): 1-128 printable ASCII characters, no spaces.
• user_id (string, required): same format.
• role (string, required): host, cohost, speaker, participant or audience.
• publish_streams (number[], optional): up to 8 unique non-zero stream ids the user may publish. Needs the publisher scope on the credential.
• subscribe_streams (number[], optional): up to 32 stream ids the user may receive. Needs the subscriber scope.
• subscribe_room (boolean, optional): receive every stream of the room. Cannot be combined with subscribe_streams.
• ttl_seconds (number, optional): lifetime, default 600, maximum 3600 or the credential's limit.
• turn (boolean, optional): also return short-lived TURN relay credentials (turn.username, turn.credential, turn.uris).
• signaling (boolean, optional): also return a token for the platform's room signaling service (signaling.token, signaling.url).
• Unknown fields are rejected. In particular a request cannot name a project or an App ID.

curl -sS https://api.fahswertc.com/v1/rtc/tokens \
  -u "$FAHSWE_APP_ID:$FAHSWE_APP_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "room_id": "live-42",
    "user_id": "u-1001",
    "role": "host",
    "publish_streams": [1, 2],
    "subscribe_room": true,
    "ttl_seconds": 600
  }'

POST /v1/rtc/tokens/revoke

Body: {"revocation_handle": "..."} with the handle returned when the token was issued. The media server closes the user's session within about a second and refuses the grant from then on. Other users are not affected. The user can come back only with a new token from your server.

A handle works only for the project that issued it. Another project's handle, or an altered one, returns 404.

Errors

Errors are JSON: {"error": "code", "message": "text"}.

• 400 invalid_request: a field is missing or not allowed (the message says which rule).
• 401 invalid_credentials: App ID or App Secret not valid.
• 403 scope_denied: the credential lacks the publisher or subscriber scope.
• 403 project_archived, 403 ip_not_allowed, 403 server_side_only (called from a browser).
• 404 unknown_handle: revocation handle not valid for this project.
• 429 rate_limited: see Retry-After.
• 502 issuer_unavailable / turn_unavailable / signaling_unavailable: temporary; retry with backoff.

Limits

• 1200 requests per minute per App ID and 2400 per client address.
• 20 failed authentications from one address within five minutes block that address for the rest of the window.
• Request body up to 8 KB.

Issue one token per user and room, and let the SDK renew it. Do not issue tokens in a loop.

Source references

• developer-platform/internal/httpserver/rtc_tokens.go
• developer-platform/internal/httpserver/rtc_tokens_test.go