Spatius API Authentication

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, 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. Spatius API access must also be enabled for the account, and avatar creation can be toggled separately from read access.

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

Example

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`
Avatar creation is disabled for the account (creation endpoint only)	`403`	`forbidden`	`API Avatar creation is disabled`

Authentication failures return the standard error envelope. A 401 response does not reveal which part of the credential pair was wrong — verify both values in Studio before retrying.

Start Here

Avatar API

Spatius API Authentication

Example

Authentication failures

Next steps

Create an Avatar

Errors and Limits

​Example

​Authentication failures

​Next steps

Create an Avatar

Errors and Limits

Example

Authentication failures

Next steps