> ## 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.

# Credentials

> App ID, Avatar ID, API Key, and Session Token — who issues each and where each is used.

Every Spatius integration uses one or more of the four credentials below. They are issued in [Spatius Studio](https://app.spatius.ai/apps) and used in different layers of your stack depending on which [integration path](/getting-started/how-to-integrate) you choose.

## 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](/api-reference/api-reference) (e.g. issuing Session Tokens), by `livekit-plugins-spatius`, by the Convo AI avatar provider, and by `spatius_avatar_python`. |
| **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)*                              |
| **Agora Convo AI Integration** | App ID + Avatar ID *(passed to the platform AvatarKit RTC client)* + Agora RTC token | API Key + App ID + Avatar ID *(via the Convo AI `avatar` provider block or `spatius_avatar_python` params)* |
| **Backend Mode**               | App ID *(passed to AvatarKit)*                                                       | API Key + App ID + Avatar ID *(used by the Server SDK to connect to Motion Server)*                         |

<Note>
  **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.
</Note>

## Getting the values

1. Create an app in [Spatius Studio](https://app.spatius.ai/apps) — you get the **App ID** and can generate an **API Key**.
2. Pick or finetune an avatar in the [Avatar Library](https://app.spatius.ai/avatars/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](/api-reference/api-reference).

## 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

<CardGroup cols={2}>
  <Card title="Choose your integration path" icon="route" href="/getting-started/how-to-integrate">
    Platform Integrations, Direct Mode, or Backend Mode.
  </Card>

  <Card title="Session token API" icon="key" href="/api-reference/api-reference">
    The exact `POST /v1/console/session-tokens` call for your backend.
  </Card>
</CardGroup>