Every Spatius integration uses one or more of the four credentials below. They are issued in Spatius Studio and used in different layers of your stack depending on which integration path you choose.Documentation Index
Fetch the complete documentation index at: https://docs.spatius.ai/llms.txt
Use this file to discover all available pages before exploring further.
The four credentials
| Credential | What it identifies | Where it lives | Where it is used |
|---|---|---|---|
| App ID | Your Spatius application. | Safe to expose on the client. | Passed to AvatarSDK.initialize() on every platform. |
| Avatar ID | Which avatar character to load. | Safe to expose on the client. | Passed to AvatarManager.load(). |
| API Key | Your account’s server-side secret. | Backend only. Never ship in client code. | Used by your backend to call the Console API (e.g. issuing Session Tokens) and by livekit-plugins-spatius running in your agent worker. |
| Session Token | A short-lived authentication for one Direct Mode session (max 24 h). | Generated on your backend per session, sent to the client. | Passed to AvatarSDK.setSessionToken() on Direct Mode clients before AvatarController.start(). |
Which credentials does each path need?
| Path | Client uses | Backend uses |
|---|---|---|
| Direct Mode | App ID + Avatar ID + Session Token | API Key (only to mint Session Tokens) |
| LiveKit Agents Integration | App ID + Avatar ID (passed to AvatarKit RTC) + LiveKit room token | API Key + App ID + Avatar ID (via SPATIUS_* env vars in your agent worker) |
| Backend Mode | App ID (passed to AvatarKit) | API Key + App ID + Avatar ID (used by the Server SDK to connect to Motion Server) |
Session Token is only needed in Direct Mode (
DrivingServiceMode.sdk), where AvatarController.start() opens a Motion Server WebSocket authenticated with the token. RTC / LiveKit Agents / Backend Mode paths use DrivingServiceMode.host; the client does not open that WebSocket, and AvatarManager.load() fetches avatar metadata over an App-ID-scoped public endpoint that does not require a Session Token.Getting the values
- Create an app in Spatius Studio — you get the App ID and can generate an API Key.
- Pick or finetune an avatar in the Avatar Library — copy its Avatar ID.
- For Direct Mode: implement a backend endpoint that calls
POST /v1/console/session-tokenson the Console API to mint Session Tokens for clients on demand. See Session token API.
Region
Spatius currently operates inus-west. Backends and SDKs default to this region — you can set SPATIUS_REGION=us-west explicitly if you prefer. The SPATIUS_CONSOLE_ENDPOINT and SPATIUS_INGRESS_ENDPOINT override env vars exist for staging and proxy setups; you do not need them for normal use.
Security checklist
- API Key stays on the backend. If it leaks, rotate immediately in Spatius Studio.
- Session Tokens are designed to be single-use and short-lived. Issue a fresh token per client session.
- App ID and Avatar ID are not secrets, but treat them as configuration: change them via env vars or config files rather than hardcoding.
Next steps
Choose your integration path
Direct Mode, LiveKit Agents Integration, or Backend Mode.
Session token API
The exact
POST /v1/console/session-tokens call for your backend.