# Machine & AI Assistant Authentication Guide

This guide describes how to configure programmatic, machine-to-machine, and AI assistant authentication across services protected by **Authentik** and **Traefik ForwardAuth**.

---

## 🎯 Use Case
When an AI assistant (or automation script, CLI tool, or cron job) needs to:
* Inspect Zigbee2MQTT logs or device states via `https://zigbee2mqtt.moritzgraf.de`
* Scrape or query metrics from `https://prometheus.haumdaucher.de`
* Trigger or query APIs protected behind the Traefik ForwardAuth gateway

Instead of interactive browser logins or hardcoding static basic auth credentials into individual ingress configs, Authentik supports **Service Accounts & API Tokens**.

---

## ⚙️ Setup Instructions

### 1. Create a Service Account in Authentik
1. Navigate to **Directory > Users** in Authentik (`https://auth.haumdaucher.de`).
2. Click **Create Service Account**:
   * **Username**: `ai-assistant` (or `mopbot`, `cli-agent`)
   * **Create API Token**: Check this box.
   * **Token Expiration**: Set to never expire (or desired TTL).
3. Copy the generated **Token Secret** (e.g. `ak_tok_xxxx...`).

### 2. Grant Access Permissions
1. Go to **Directory > Groups**.
2. Add the `ai-assistant` service account to the appropriate group (e.g. `infra-admins` or `zigbee-readers`).
3. Ensure the Application/Proxy Provider policy allows this group.

---

## 💻 Making Authenticated API Calls

### HTTP Bearer Token (Recommended)
Pass the API token in the `Authorization` header:

```bash
curl -H "Authorization: Bearer <your-authentik-token>" \
     https://zigbee2mqtt.moritzgraf.de/api/bridge/info
```

When Traefik ForwardAuth queries Authentik with this header, Authentik detects the Bearer token, authenticates the `ai-assistant` service account, checks permissions, and responds with HTTP `200 OK`. Traefik then proxies the request directly to the backend.

### Python / Scripting Example

```python
import requests

AUTH_TOKEN = "your-authentik-token"
headers = {
    "Authorization": f"Bearer {AUTH_TOKEN}",
    "Accept": "application/json"
}

response = requests.get("https://zigbee2mqtt.moritzgraf.de/api/bridge/devices", headers=headers)
print(response.json())
```

---

## 🔄 Rotating & Revoking Tokens
* To rotate a token, navigate to **Directory > Tokens and App passwords**.
* You can view active tokens, inspect last-used timestamps, and revoke compromised tokens instantly with one click without restarting any Kubernetes pods or modifying ingress secrets.