Skip to main content
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.

​
The four credentials

CredentialWhat it identifiesWhere it livesWhere it is used
App IDYour Spatius application.Safe to expose on the client.Passed to AvatarSDK.initialize() on every platform.
Avatar IDWhich avatar character to load.Safe to expose on the client.Passed to AvatarManager.load().
API KeyYour 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), by livekit-plugins-spatius, by the Convo AI avatar provider, and by spatius_avatar_python.
Session TokenA 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?

PathClient usesBackend uses
Direct ModeApp ID + Avatar ID + Session TokenAPI Key (only to mint Session Tokens)
LiveKit Agents IntegrationApp ID + Avatar ID (passed to AvatarKit RTC) + LiveKit room tokenAPI Key + App ID + Avatar ID (via SPATIUS_* env vars in your agent worker)
Agora Convo AI IntegrationApp ID + Avatar ID (passed to the platform AvatarKit RTC client) + Agora RTC tokenAPI Key + App ID + Avatar ID (via the Convo AI avatar provider block or spatius_avatar_python params)
Backend ModeApp 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.direct), where AvatarController.start() opens a Motion Server WebSocket authenticated with the token. RTC / Platform Integration / Backend Mode paths use DrivingServiceMode.backend; 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

  1. Create an app in Spatius Studio — you get the App ID and can generate an API Key.
  2. Pick or finetune an avatar in the Avatar Library — copy its Avatar ID.
  3. For Direct Mode: implement a backend endpoint that calls POST /v1/console/session-tokens on the Console API to mint Session Tokens for clients on demand. See Session token API.

​
Region

Spatius currently operates in us-west, ap-northeast, and cn-beijing. Backends and SDKs default to us-west; set SPATIUS_REGION when your app should use another supported region. 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

Platform Integrations, Direct Mode, or Backend Mode.

Session token API

The exact POST /v1/console/session-tokens call for your backend.