Home Assistant API Authentifizierung sicher einrichten und testen

Du willst Daten von einer externen Quelle in Home Assistant holen, zum Beispiel Strompreise, Wetterdaten oder den Status deiner Solaranlage. Du findest eine API, probierst den REST-Sensor aus und bekommst eine Fehlermeldung. Grund: Die API verlangt eine Authentifizierung. Du musst dich "ausweisen", bevor du Daten bekommst. Im Video zeige ich dir die zwei gängigen Methoden und wie du sie in YAML konfigurierst.

Kurz erklärt: Was ist eine API?

API steht für "Application Programming Interface". Das ist eine Schnittstelle, über die zwei Systeme miteinander reden. Home Assistant schickt eine Anfrage an eine URL (den "Endpoint"), und die API schickt Daten zurück, meistens im JSON-Format. Das sieht dann ungefähr so aus:

{
  "temperature": 22.5,
  "humidity": 48,
  "status": "online"
}

Home Assistant liest diese Daten aus und macht daraus Sensoren, die du im Dashboard anzeigen oder in Automationen verwenden kannst.

Das Problem: Die meisten APIs geben ihre Daten nicht einfach so her. Du brauchst Zugangsdaten. Entweder einen API-Key (Token) oder Benutzername und Passwort.

Voraussetzungen

• Home Assistant mit Zugang zur configuration.yaml. Ob du die Datei per File Editor App (früher Add-on), VS Code App oder Samba-Share bearbeitest, ist egal.
• Den API-Key oder die Zugangsdaten der Schnittstelle die du ansprechen willst. Wo du den bekommst, steht in der Dokumentation der jeweiligen API. Meistens musst du dich registrieren und findest den Key in deinem Account-Bereich.

Methode 1: Bearer Token (API-Key)

Die meisten modernen APIs arbeiten mit einem Token. Du bekommst einen langen String (den API-Key) und schickst ihn bei jeder Anfrage im HTTP-Header mit. Das ist die gängigste Methode.

In Home Assistant nutzt du dafür die rest:-Integration. Der Token kommt in den Authorization-Header mit dem Prefix Bearer:

1rest:
2  - resource: "https://api.example.com/v1/production"
3    scan_interval: 60
4    headers:
5      Authorization: "Bearer DEIN_API_TOKEN"
6      Content-Type: "application/json"
7    sensor:
8      - name: "Solar Produktion"
9        unique_id: solar_api_produktion
10        value_template: "{{ value_json.current_power }}"
11        unit_of_measurement: "W"
12        device_class: power
13        state_class: measurement

Was passiert hier im Detail:

• resource: Die URL der API. Ersetze das mit deinem echten Endpoint.
• scan_interval: 60: Home Assistant fragt alle 60 Sekunden die API ab. Nicht zu niedrig setzen, manche APIs haben Rate Limits (z.B. max. 100 Anfragen pro Stunde).
• headers: Hier stehen die HTTP-Header. Authorization mit Bearer ist der Standard. Manche APIs nutzen statt Bearer einen eigenen Header wie X-API-Key oder api-key. Schau in die API-Doku welcher Header erwartet wird.
• sensor: Die Sensoren die aus der API-Antwort erstellt werden. Du kannst hier mehrere Sensoren unter einem rest:-Block definieren, die alle dieselbe API-Antwort auswerten. Das spart API-Calls.
• unique_id: Interne Kennung. Damit kannst du den Sensor später in der UI umbenennen oder das Icon ändern, ohne die YAML anzufassen.
• device_class und state_class: Damit weiß Home Assistant, was der Wert bedeutet. device_class: power sorgt für das richtige Icon und die richtige Einheit. state_class: measurement macht den Sensor im Energy Dashboard und in Langzeitstatistiken nutzbar.

Methode 2: Basic Auth (Benutzername + Passwort)

Lokale Geräte und ältere APIs nutzen oft Basic Auth. Das heißt: Benutzername und Passwort werden bei jeder Anfrage mitgeschickt. Home Assistant unterstützt das direkt über die Parameter username, password und authentication:

1rest:
2  - resource: "http://192.168.1.1/api/status"
3    authentication: basic
4    username: "admin"
5    password: "dein_passwort"
6    scan_interval: 300
7    sensor:
8      - name: "Router Uptime"
9        unique_id: router_uptime
10        value_template: "{{ value_json.uptime }}"

Der Parameter authentication akzeptiert zwei Werte: basic und digest. In 95% der Fälle ist es basic. Digest Auth kommt nur bei wenigen, meist älteren Systemen vor.

Wichtig: Basic Auth schickt die Zugangsdaten Base64-kodiert, aber nicht verschlüsselt. Über http:// (ohne TLS) können sie im Netzwerk mitgelesen werden. Im lokalen Netzwerk ist das meistens okay. Falls du eine externe API mit Basic Auth ansprichst, achte darauf dass die URL mit https:// beginnt.

Mehrere Sensoren aus einer API

Wenn eine API mehrere Werte in einer Antwort liefert, brauchst du nicht für jeden Wert einen eigenen API-Call. Definiere einfach mehrere Sensoren unter demselben rest:-Block:

1rest:
2  - resource: "https://api.wetterdienst.de/v1/current"
3    scan_interval: 600
4    headers:
5      Authorization: !secret wetter_api_token
6    sensor:
7      - name: "Außentemperatur API"
8        unique_id: wetter_api_temp
9        value_template: "{{ value_json.temperature }}"
10        unit_of_measurement: "°C"
11        device_class: temperature
12        state_class: measurement
13      - name: "Luftfeuchtigkeit API"
14        unique_id: wetter_api_humidity
15        value_template: "{{ value_json.humidity }}"
16        unit_of_measurement: "%"
17        device_class: humidity
18        state_class: measurement
19      - name: "Windgeschwindigkeit API"
20        unique_id: wetter_api_wind
21        value_template: "{{ value_json.wind_speed }}"
22        unit_of_measurement: "km/h"
23        device_class: wind_speed
24        state_class: measurement

Home Assistant macht einen API-Call alle 10 Minuten und verteilt die Werte auf drei Sensoren. Ohne diesen Trick wären es drei separate Calls.

Komplexe JSON-Antworten auswerten

Nicht jede API liefert flache Key-Value-Paare. Oft sind die Daten verschachtelt. Dafür gibt es json_attributes_path und json_attributes. Angenommen die API antwortet so:

1{
2  "data": {
3    "solar": {
4      "power": 3200,
5      "energy_today": 18.4
6    }
7  }
8}

Dann kommst du mit value_template allein nicht weit. Stattdessen:

1rest:
2  - resource: "https://api.solar.example/v1/status"
3    scan_interval: 30
4    headers:
5      Authorization: !secret solar_token
6    sensor:
7      - name: "Solar API"
8        unique_id: solar_api_raw
9        json_attributes_path: "$.data.solar"
10        json_attributes:
11          - power
12          - energy_today
13        value_template: "OK"

Der Sensor selbst zeigt nur "OK" an, aber die eigentlichen Werte stecken in den Attributen. Um daraus eigene Sensoren zu machen, nutzt du Template-Sensoren:

1template:
2  - sensor:
3      - name: "Solar Leistung"
4        unique_id: solar_leistung
5        state: "{{ state_attr('sensor.solar_api', 'power') }}"
6        unit_of_measurement: "W"
7        device_class: power
8        state_class: measurement
9      - name: "Solar Energie heute"
10        unique_id: solar_energie_heute
11        state: "{{ state_attr('sensor.solar_api', 'energy_today') }}"
12        unit_of_measurement: "kWh"
13        device_class: energy
14        state_class: total_increasing

Dieses Muster (REST-Sensor holt Rohdaten, Template-Sensoren extrahieren einzelne Werte) nutze ich bei den meisten meiner API-Integrationen. Es hält die REST-Konfiguration sauber und die Template-Sensoren lassen sich unabhängig anpassen.

API-Tokens sicher speichern

Tokens und Passwörter gehören nicht direkt in die configuration.yaml. Wenn du die Datei teilst, ein Backup weitergibst oder die Config in Git versionierst, sind die Zugangsdaten sonst mit dabei.

Stattdessen nutzt du die secrets.yaml. Die liegt im selben Ordner wie deine configuration.yaml:

# secrets.yaml
solar_token: "Bearer s3cr3t_t0k3n_123456"
wetter_api_token: "Bearer wetter_abc_789"
router_password: "mein_sicheres_passwort"

In der configuration.yaml referenzierst du den Wert dann mit !secret:

rest:
  - resource: "https://api.solar.example/v1/status"
    headers:
      Authorization: !secret solar_token

Home Assistant ersetzt !secret solar_token automatisch durch den Wert aus der secrets.yaml. Der Wert muss den kompletten Header-Inhalt enthalten, also inklusive Bearer wenn nötig.

Hinweis: !secret funktioniert nicht im YAML-Editor der HA-Oberfläche (z.B. beim Bearbeiten von Automationen über die UI). Es funktioniert nur in YAML-Dateien die direkt geladen werden (configuration.yaml, Packages, etc.).

Vor der YAML: Erstmal mit curl testen

Bevor du YAML schreibst und bei Fehlern rätselst ob es an deiner Konfiguration oder an der API liegt, teste den API-Call im Terminal. Das geht am schnellsten mit curl:

1# Bearer Token testen
2curl -s -H "Authorization: Bearer DEIN_TOKEN" \
3     "https://api.example.com/v1/data"
4
5# Basic Auth testen
6curl -s -u admin:passwort \
7     "http://192.168.1.1/api/status"
8
9# Wenn du die Antwort formatiert sehen willst
10curl -s -H "Authorization: Bearer DEIN_TOKEN" \
11     "https://api.example.com/v1/data" | python3 -m json.tool

Wenn curl eine JSON-Antwort liefert, weißt du: Die Zugangsdaten stimmen, die URL ist richtig, die API antwortet. Dann kannst du die URL und die Header 1:1 in deine YAML übernehmen.

Falls du kein Terminal zur Hand hast: Im Browser funktioniert Bearer Auth nicht direkt, aber Tools wie Hoppscotch (kostenlos, kein Account nötig) lassen dich API-Calls mit Headern testen.

Home Assistant eigene API ansprechen

Nicht nur externe APIs brauchen Authentifizierung. Auch die Home Assistant API selbst ist geschützt. Wenn du von einem externen Script, einer anderen Anwendung oder einem Webhook-Service auf deine HA-Daten zugreifen willst, brauchst du einen Long-Lived Access Token.

Den erstellst du in Home Assistant unter Profil (klick auf deinen Namen unten links) → Tab Sicherheit → Abschnitt Langlebige Zugriffstoken → Token erstellen. Gib dem Token einen Namen (z.B. "Externes Script") und kopiere ihn sofort. Er wird nur einmal angezeigt.

1# HA-API: Status eines Sensors abfragen
2curl -s \
3     -H "Authorization: Bearer DEIN_HA_TOKEN" \
4     -H "Content-Type: application/json" \
5     "http://homeassistant.local:8123/api/states/sensor.temperatur_wohnzimmer"
6
7# HA-API: Service aufrufen (z.B. Licht einschalten)
8curl -s -X POST \
9     -H "Authorization: Bearer DEIN_HA_TOKEN" \
10     -H "Content-Type: application/json" \
11     -d '{"entity_id": "light.wohnzimmer"}' \
12     "http://homeassistant.local:8123/api/services/light/turn_on"

Pass die Adresse an deine Instanz an: Neue Installationen von Home Assistant OS laufen seit 2026.8 auf Port 80 (http://homeassistant.local). Bestehende Installationen behalten ihren Port, Home Assistant Container bleibt bei 8123.

YAML einfügen und aktivieren

1. Backup erstellen: Einstellungen → System → Backup → "Backup jetzt erstellen". Mach das vor jeder YAML-Änderung.
2. YAML bearbeiten: Öffne die configuration.yaml über die File Editor App (Sidebar), die VS Code App oder per Samba-Share. Kopiere den rest:-Block ans Ende der Datei. Wichtig: rest: muss ganz links stehen, ohne Einrückung. Falls du schon einen rest:-Block hast, füge den neuen Inhalt darunter ein (nicht den Key doppelt anlegen).
3. Konfiguration prüfen: Werkzeuge → YAML (Tab oben, bis 2026.7 Entwicklerwerkzeuge) → "Konfiguration prüfen". Erst wenn dort "Konfiguration gültig" steht, weiter.
4. Neu starten: Auf derselben Seite "Neu starten" klicken. Der Neustart dauert 1-2 Minuten.

Häufige Fehler und Lösungen

401 Unauthorized / 403 Forbidden: Der Token oder die Zugangsdaten stimmen nicht. Prüfe mit curl ob der Token noch gültig ist. Manche APIs haben Tokens die ablaufen. Bei Bearer Tokens: Prüfe ob der Prefix Bearer (mit Leerzeichen!) dabei ist.

"mapping values are not allowed here": Einrückungsfehler in der YAML. Häufigste Ursache: Tabs statt Leerzeichen. YAML erlaubt nur Leerzeichen. Im File Editor siehst du Tabs als breitere Einrückung. Ersetze sie durch 2 Leerzeichen pro Ebene.

Sensor zeigt "unknown" oder "unavailable": Die API antwortet, aber dein value_template passt nicht zur JSON-Struktur. Geh in Werkzeuge → Template und teste den Ausdruck dort. Oder schau dir die Rohdaten an: Werkzeuge → Zustände → nach deinem Sensor suchen → Attribute aufklappen.

SSL-Fehler bei lokalen APIs: Lokale Geräte mit selbst-signierten Zertifikaten brauchen verify_ssl: false im rest:-Block:

1rest:
2  - resource: "https://192.168.1.50/api/data"
3    verify_ssl: false
4    headers:
5      Authorization: !secret lokale_api_token
6    sensor:
7      - name: "Lokales Gerät"
8        value_template: "{{ value_json.value }}"

Rate Limiting: Manche APIs erlauben nur eine begrenzte Anzahl Anfragen pro Stunde oder Tag. Setze scan_interval hoch genug. Für die meisten Anwendungen reichen 60-300 Sekunden. Strompreise? Alle 15 Minuten. Wetterdaten? Alle 10 Minuten. Solaranlage? Alle 30-60 Sekunden.

POST-Requests

Manche APIs erwarten statt einem GET-Request einen POST-Request, zum Beispiel GraphQL-APIs. Das konfigurierst du mit method: POST und payload:

1rest:
2  - resource: "https://api.example.com/graphql"
3    method: POST
4    scan_interval: 300
5    headers:
6      Authorization: !secret api_token
7      Content-Type: "application/json"
8    payload: >-
9      {"query": "{ currentUser { name energy { consumption } } }"}
10    sensor:
11      - name: "API Verbrauch"
12        unique_id: api_verbrauch
13        value_template: "{{ value_json.data.currentUser.energy.consumption }}"

Ein reales Beispiel dafür ist die Tibber GraphQL-API, die ich in einem anderen Video komplett durchgehe.