Skip to main content
The Aris API uses Bearer token authentication. You’ll need an API token to access most endpoints.

​
Getting an API Token

  1. Open the Aris web UI at http://aris.local
  2. Go to Settings → API Tokens
  3. Click Create Token and give it a descriptive name (e.g., “Home Assistant”, “Grafana”)
  4. Copy the token immediately—it’s only shown once
Save the token immediately! The full token is only shown once and cannot be retrieved later.

​
Using Your Token

Include the token in the Authorization header of every request: 
curl http://aris.local/api/zones \
  -H "Authorization: Bearer YOUR_API_TOKEN"
Or in Python: 
import requests

response = requests.get(
    "http://aris.local/api/zones",
    headers={"Authorization": "Bearer YOUR_API_TOKEN"}
)

​
Which Endpoints Require Auth?

EndpointsAuth Required
/health, /readyNo
/firmware/*No
All /api/* endpointsYes
/prometheus/*Yes

​
Managing Tokens

You can view and delete tokens in the Aris web UI under Settings → API Tokens. Each token shows:
  • Name - The label you gave it
  • Created - When it was created
  • Last Used - When it was last used for an API call
Delete tokens that are no longer needed or if you suspect they’ve been compromised.

​
Best Practices

Name tokens after their purpose: “Home Assistant”, “Grafana Dashboard”, “Backup Script”. This helps you identify what might break if you delete a token.
Don’t share tokens between services. If one is compromised, you can revoke it without affecting others.
Never commit tokens to git or expose them in logs. Use environment variables or secret managers.
Check the “Last Used” timestamp. Delete tokens that haven’t been used in months.

​
Error Responses

​
401 Unauthorized

If you see this error, your token is missing, invalid, or expired: 
{
  "error": "Unauthorized",
  "message": "Valid authentication required"
}
Common causes:
  • Missing Authorization header
  • Typo in the token
  • Token was deleted
  • Using Bearer prefix incorrectly (should be Bearer YOUR_TOKEN, not Bearer: YOUR_TOKEN)