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

# Session Token Auth Flow

> How Direct Mode clients obtain and use Spatius Session Tokens without exposing backend API Keys.

<Note>
  **This flow only applies to Direct Mode** (`DrivingServiceMode.direct`), where the client opens a Motion Server WebSocket from `AvatarController.start()`. The recommended RTC integrations use `DrivingServiceMode.rtc`; Backend Mode uses `DrivingServiceMode.backend`. None of those paths opens that client-side Motion Server WebSocket or needs a Spatius Session Token.
</Note>

## Before you start

Open [Apps](https://app.spatius.ai/apps), select your app, then copy its App ID and generate an API Key under **Developer → API Key**. Session Token issuance requires a server-side component — implement an authentication endpoint on your own business server and keep the API Key there.

The flow involves two distinct Spatius services:

* **Console API** — issues Session Tokens. Your business server calls this with your API Key.
* **Motion Server** — handles avatar runtime connections. The Direct Mode AvatarKit client connects here using the Session Token.

## Connection flow

1. The client sends an authentication request to your business server.
2. The business server sends a request to the **Spatius Console API** to generate a Session Token, including expiration time in the request body and the API Key in the `X-API-Key` header.
3. The Console API returns the Session Token to your business server.
4. The business server returns the Session Token to the client.
5. The client sets the token on `AvatarSDK`, then starts its `AvatarController`. The exact setter differs by platform.
6. The controller opens the **Motion Server** WebSocket authenticated with the Session Token.

```mermaid theme={null}
sequenceDiagram
    participant Client
    participant BizServer as Business Server
    participant Console as Console API
    participant Motion as Motion Server
    participant Kit as AvatarKit

    Client->>BizServer: Authentication request
    BizServer->>Console: Generate Session Token (API Key + expireAt)
    Console-->>BizServer: Return Session Token
    BizServer-->>Client: Return Session Token
    Client->>Kit: Set Session Token + start controller
    Kit->>Motion: Open WebSocket (Session Token)
    Motion-->>Kit: Connection response
    Note over Motion,Kit: After token expiration, new connections are rejected<br>Existing connections are not affected
```

## Token expiration

If you attempt to establish a new connection after the token's configured expiration time, it will be rejected. Existing established connections are not affected.

## Notes

* Avoid leaking your API Key; ensure it is only used on the server.
* Keep Session Tokens short-lived and issue a fresh token for each new connection.

> For the endpoint shape and request fields, see the [Session Token API](/api-reference/api-reference).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.