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 Add-on, VS Code Add-on 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: measurementWas 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.AuthorizationmitBearerist der Standard. Manche APIs nutzen stattBearereinen eigenen Header wieX-API-Keyoderapi-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 einemrest:-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_classundstate_class: Damit weiß Home Assistant, was der Wert bedeutet.device_class: powersorgt für das richtige Icon und die richtige Einheit.state_class: measurementmacht 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: measurementHome 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_increasingDieses 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_tokenHome 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.toolWenn 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) → ganz nach unten scrollen → 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"YAML einfügen und aktivieren
- Backup erstellen: Einstellungen → System → Sicherungen → Sicherung erstellen. Mach das vor jeder YAML-Änderung.
- YAML bearbeiten: Öffne die
configuration.yamlüber das File Editor Add-on (Sidebar), das VS Code Add-on oder per Samba-Share. Kopiere denrest:-Block ans Ende der Datei. Wichtig:rest:muss ganz links stehen, ohne Einrückung. Falls du schon einenrest:-Block hast, füge den neuen Inhalt darunter ein (nicht den Key doppelt anlegen). - Konfiguration prüfen: Entwicklerwerkzeuge → YAML (Tab oben) → "Konfiguration prüfen". Erst wenn dort "Konfiguration gültig" steht, weiter.
- 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 Entwicklerwerkzeuge → Template und teste den Ausdruck dort. Oder schau dir die Rohdaten an: Entwicklerwerkzeuge → 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.
