---
title: Provider concepts
description: How provider configuration works — what you own, what the platform owns, and why credentials never touch the frontend.
sidebar:
  label: Provider concepts
  order: 5
---

:::warning[This page is a placeholder — content is under review]
The public scope of provider documentation is a **pending product decision**:
which providers are public, which are partner-facing, and which fields may be
documented publicly have not been finalized.

What you see here is the **conceptual ownership model only** — the parts that
are already fixed by the platform's public contract. Provider-specific setup
guides, field-level configuration tables, and examples with real credential
formats are intentionally omitted and will appear (or not) once the public
boundary decision lands. Where examples are needed below, credential values are
**redacted placeholders**, not real formats.
:::

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:

<Columns cols={2}>

<Card title="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.
</Card>

<Card title="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.
</Card>

</Columns>

## What reaches your frontend

The session create response gives the browser exactly two things and nothing
else:

1. The **`ws_url`** — the media WebSocket URL with the embedded short-lived
   client token.
2. Stream **metadata** — transport type and token expiry.

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](/reference/sessions/post-v1-sessions) — request schema
  and provider fields
- [Provider config schema](/reference) — full component schema listing