> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ariscomfort.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> How to authenticate with the Aris API

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

<Warning>
  **Save the token immediately!** The full token is only shown once and cannot be retrieved later.
</Warning>

## Using Your Token

Include the token in the `Authorization` header of every request:

```bash theme={null}
curl http://aris.local/api/zones \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```

Or in Python:

```python theme={null}
import requests

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

## Which Endpoints Require Auth?

| Endpoints              | Auth Required |
| ---------------------- | ------------- |
| `/health`, `/ready`    | No            |
| `/firmware/*`          | No            |
| All `/api/*` endpoints | Yes           |
| `/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

<AccordionGroup>
  <Accordion title="Use descriptive token names">
    Name tokens after their purpose: "Home Assistant", "Grafana Dashboard", "Backup Script". This helps you identify what might break if you delete a token.
  </Accordion>

  <Accordion title="Create separate tokens for each integration">
    Don't share tokens between services. If one is compromised, you can revoke it without affecting others.
  </Accordion>

  <Accordion title="Store tokens securely">
    Never commit tokens to git or expose them in logs. Use environment variables or secret managers.
  </Accordion>

  <Accordion title="Regularly audit your tokens">
    Check the "Last Used" timestamp. Delete tokens that haven't been used in months.
  </Accordion>
</AccordionGroup>

## Error Responses

### 401 Unauthorized

If you see this error, your token is missing, invalid, or expired:

```json theme={null}
{
  "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`)