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

# Spatius API Authentication

> Authenticate Spatius API requests with the X-App-ID and X-API-Key header pair.

Every Spatius API request must carry two headers:

| Header | Value |
| - | - |
| `X-App-ID` | Your Spatius App ID |
| `X-API-Key` | The API key bound to that App ID |

Both values come from your application in [Spatius Studio](https://app.spatius.ai), the same credentials you use for `SPATIUS_APP_ID` and `SPATIUS_API_KEY`. The pair must match exactly: the API key must be the one bound to the given App ID, and the application's owner account must be active. Avatar API and Video API access are enabled separately for the account. Each API can allow reads while creation is paused. Apps owned by one account share its jobs and limits.

<Warning>
  Call the Spatius API from your backend only. Never embed the API key in client-side code, mobile apps, or public repositories.
</Warning>

## Example

```bash theme={null}
curl --request POST 'https://console.spatius.ai/v1/open/avatars' \
  --header 'X-App-ID: <your-app-id>' \
  --header 'X-API-Key: <your-api-key>' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "name": "Support Agent",
    "imageUrl": "https://example.com/portraits/agent.png"
  }'
```

## Authentication failures

| Situation | HTTP status | Error code | Message |
| - | - | - | - |
| Either header missing, the pair does not match, or the owner account is inactive | `401` | `unauthorized` | — |
| API access is not configured for the account | `403` | `forbidden` | `Open API access is not configured` |
| Video access is not configured, creation is paused, or the Avatar is not allowed | `403` | `forbidden` | See [Video access](/api-reference/video-generation#access-and-safe-retries). |
| Avatar creation is disabled for the account (creation endpoint only) | `403` | `forbidden` | `API Avatar creation is disabled` |

Authentication failures return the standard [error envelope](/api-reference/errors). A `401` response does not reveal which part of the credential pair was wrong — verify both values in Studio before retrying.

## Next steps

<CardGroup cols={2}>
  <Card title="Create an Avatar" icon="image" href="/api-reference/avatars/create-an-avatar" />

  <Card title="Errors and Limits" icon="triangle-exclamation" href="/api-reference/errors" />
</CardGroup>


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