docs: Home-Assistant-Status in api.md

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

docs/api.md

@@ -29,6 +29,7 @@ In der Entwicklungsumgebung ist die interaktive Dokumentation unter `/docs` (Swa
 19. [Admin · Mandanten & Reseller](#admin--mandanten--reseller)
 20. [Sondervertretungen](#sondervertretungen)
 21. [Admin · TLS](#admin--tls)
+22. [Home-Assistant-Status](#home-assistant-status)
 
 ---
 
@@ -1800,3 +1801,84 @@ Internes Zertifikat erneuern (Hostname/IP, kein öffentlicher Certbot-Weg).
 **Request:** `{ "hostname": "timemaster", "ip": "192.168.1.137" }`
 
 **Response:** `TlsStatusOut`
+
+---
+
+## Home-Assistant-Status
+
+Router-Präfix: `/time` (Status) bzw. `/users/me` (Token-Verwaltung)
+
+Read-only JSON-Status der eigenen Arbeitszeit für einen REST-Sensor in Home
+Assistant. **Kein JWT** (Access-Token läuft nach 30 min ab, Refresh rotiert):
+Zugang über ein geheimes, rotierbares, opt-in Token in der URL (gehasht in
+`users.ha_token_hash`, Migration 0048). Liefert ausschließlich die eigenen
+Daten des Token-Inhabers. Ohne TLS ist das Token mitlesbar.
+
+### `GET /time/ha/{token}`
+
+- **Erforderliche Rolle:** öffentlich (kein JWT, Token in URL)
+
+**Response:**
+```json
+{
+  "status": "out | working | break",
+  "stamped_in_since": "2026-10-28T07:30:00+00:00 | null",
+  "worked_today_min": 255,
+  "break_today_min": 30,
+  "month_worked_h": 80.5,
+  "month_expected_h": 84.0,
+  "month_balance_h": -3.5,
+  "updated_at": "2026-10-28T11:45:00+00:00"
+}
+```
+
+Zeiten sind UTC. `month_*` zählt nur genehmigte Einträge (wie `/time/balance/me`).
+
+---
+
+### `GET /users/me/ha-token`
+
+Status abfragen. Das Token selbst wird nie zurückgegeben.
+
+- **Erforderliche Rolle:** authentifiziert (jede Rolle)
+
+**Response:** `{ "enabled": true|false }`
+
+---
+
+### `POST /users/me/ha-token`
+
+Erzeugt ein neues Token (rotiert ein bestehendes), URL **einmalig** in der Antwort.
+Im Frontend: ProfilePage → „Home Assistant".
+
+- **Erforderliche Rolle:** authentifiziert (jede Rolle)
+
+**Response:** `{ "enabled": true, "url": "https://.../api/v1/time/ha/<token>" }`
+
+---
+
+### `DELETE /users/me/ha-token`
+
+Deaktivieren (Token löschen).
+
+- **Erforderliche Rolle:** authentifiziert (jede Rolle)
+
+**Response:** `204 No Content`
+
+### Home-Assistant-Konfiguration
+
+URL in `secrets.yaml` ablegen (enthält das Token):
+
+```yaml
+sensor:
+  - platform: rest
+    name: Arbeitszeit
+    resource: !secret timemaster_ha_url
+    value_template: "{{ value_json.status }}"
+    json_attributes:
+      - worked_today_min
+      - break_today_min
+      - month_balance_h
+      - stamped_in_since
+    scan_interval: 60
+```