Provider concepts

How provider configuration works — what you own, what the platform owns, and why credentials never touch the frontend.

A “provider” is the external service that powers part of an avatar session — for example the real-time voice service a session is built on. Sessions name a provider and hand it per-session credentials; the platform connects to that provider on the session’s behalf.

The ownership model

The fixed, contract-level framing — independent of which providers end up publicly documented:

What YOU own

Your credentials. You mint short-lived provider tokens with the provider; the platform never stores them.
Session creation. Your backend calls POST /v1/sessions with a provider_type and matching provider_config.
The lifecycle. You end sessions, handle reconnects, and manage your own token minting cadence.

What the PLATFORM owns

The connection to the provider for the session’s lifetime — provider infrastructure is invisible in public responses.
Credential hygiene. Your per-session provider credentials are held in memory only and zeroed at session end — never persisted, never logged.
The public contract. Six endpoints, stable error codes, no infrastructure concepts leaked into responses.

What reaches your frontend

The session create response gives the browser exactly what it needs to connect, and nothing else:

The client_token — a short-lived (5-minute) HMAC-signed token, delivered exactly once. The frontend appends it to the media WebSocket URL as ?token=; stream_metadata.session_token is the purpose-scoped media-plane alternative.
stream_metadata — the media-plane connection metadata: transport, sfu_endpoint, session_token, and ice_servers. The expires_at field carries the token expiry in epoch milliseconds.

Provider credentials never appear here. They exist only in the backend-to-platform call that created the session.

Why per-session credentials

The platform accepts only ephemeral, per-session provider credentials:

They limit blast radius — a leaked session token outlives nothing.
They keep the platform storage-free for your credentials: memory-only, zeroed at end, never in any persistence layer.
They make rotation your backend’s decision — mint fresh per session, and a compromised provider token simply expires.

Placeholder: provider-specific guides

The following are intentionally not documented yet, pending the public-boundary decision:

Which provider types are publicly documentable (beyond what the generated provider_type enum already exposes).
Field-level provider_config tables per provider.
Credential minting walkthroughs per provider (redacted formats included).
External/private engine integrations — a separate partner track, out of scope for the public docs.

For the exact provider_type values and the provider_config schema the platform accepts today, see the generated reference — it is the authoritative contract:

POST /v1/sessions — request schema and provider fields
Provider config schema — full component schema listing