UniFi Protect in Home Assistant einbinden: lokaler Benutzer und API-Schlüssel

UniFi Protect und Home Assistant sind zwei Systeme, die eigentlich für einander gemacht sind: Auf der einen Seite Kameras, Türklingeln, Bewegungsmelder und Chimes von Ubiquiti, auf der anderen Seite die Smart-Home-Zentrale, die alles zusammenführt. Wenn du beides verbindest, landen deine Kamerabilder, Bewegungs- und Objekterkennungen sowie die Sensordaten direkt in Home Assistant – lokal, ohne Cloud-Umweg, ohne Abo. Genau das machen wir in diesem Artikel Schritt für Schritt. Das hier ist Teil 1 einer kleinen Serie: Wir bauen zuerst das Fundament, also die Verbindung zwischen Protect und Home Assistant. In Teil 2 geht es um den SuperLink-Bewegungsmelder, in Teil 3 darum, wie du UniFi-Fobs per Webhook in Automationen einbindest.

Wichtig vorab: Ubiquiti hat den Weg zum API-Schlüssel verschoben. Wenn du den Menüpunkt nach einer Anleitung nicht gefunden hast – du hast nichts falsch gemacht, die Anleitung war veraltet. Alles hier ist an einer echten Konsole mit UniFi OS 5.1.31 und Protect 7.2.105 nachgeprüft (Stand September 2026). Falls Home Assistant bei dir noch gar nicht läuft, findest du den Einstieg in unserem Guide Home Assistant einrichten; für die UniFi-Seite hilft der UniFi-Einrichtungs-Guide.

Zwei Wege — und warum die Wahl wichtig ist

Home Assistant fragt dich beim Einrichten der Integration als Allererstes, wie du dich mit der Konsole verbinden willst. Das ist keine Formsache, sondern die wichtigste Entscheidung im ganzen Prozess – sie legt fest, welche Entitäten du hinterher überhaupt bekommst. Der Dialog formuliert es unmissverständlich: „Wähle die Verbindungsart zu deiner UniFi Protect-Konsole. Der Modus ‚Nur API-Schlüssel‘ bietet derzeit nur einen begrenzten Umfang an Entitäten: den Alarmmanager, Kameras (Streams und Schnappschüsse) und Leuchten. Für alles andere ist ein lokaler Benutzer erforderlich.“

Konkret heißt das:

• Nur API-Schlüssel (eingeschränkter Funktionsumfang): Du bekommst den Alarmmanager, deine Kameras mit Live-Stream und Schnappschuss sowie die Leuchten. Das war es. Kein Bewegungssensor, keine Objekterkennung, keine Diagnosewerte.
• Lokaler Benutzer und API-Schlüssel (Vollzugriff): Alles andere – und das ist der spannende Teil. Bewegungs- und Objekterkennung als Sensoren, Türklingel-Events, Chimes, Doorlocks, Diagnosewerte wie Speicherbelegung und Laufzeit. Erst damit wird Protect in Home Assistant zu einer Automationsquelle statt zu einer reinen Bildergalerie.

Meine klare Empfehlung: Nimm den Vollzugriff. Der eingeschränkte Modus lohnt nur, wenn du wirklich ausschließlich Kamerabilder auf ein Dashboard legen willst. Sobald du „wenn die Einfahrtskamera eine Person erkennt, mach das Licht an“ automatisieren möchtest, brauchst du den lokalen Benutzer – und richtest die Integration dann ohnehin neu ein.

Noch ein Wort zur Qualität: UniFi Protect trägt in Home Assistant das Qualitätssiegel Platin – die höchste Stufe. Kein Bastelprojekt, sondern eine der am besten gepflegten Integrationen überhaupt.

Schritt 1: Lokalen Benutzer in UniFi OS anlegen

Der Vollzugriff-Dialog sagt es selbst: „Du benötigst einen lokalen Benutzer, der in deiner UniFi OS Console erstellt wurde, um dich damit anzumelden. Ubiquiti Cloud-Benutzer funktionieren nicht.“ Das ist der Punkt, an dem die meisten hängenbleiben. Dein normales Ubiquiti-Konto – also das, mit dem du dich bei unifi.ui.com anmeldest – ist ein Cloud-Konto. Home Assistant kann damit nichts anfangen, weil die Anmeldung gegen die Konsole selbst läuft und nicht gegen Ubiquitis Server. Du brauchst also ein Konto, das auf der Konsole existiert.

Leg dieses Konto in den UniFi-OS-Einstellungen unter der Benutzerverwaltung neu an – als eigenständiges Konto nur für Home Assistant, nicht als Zweitnutzung deines Admin-Accounts. Du siehst dann in den Protokollen sofort, welche Zugriffe von Home Assistant kommen, kannst das Konto jederzeit sperren, ohne dich selbst auszusperren, und die Rechte klein halten.

Worauf du achten solltest:

• Sprechender Name: Nenn den Benutzer homeassistant oder ha. In zwei Jahren weißt du sonst nicht mehr, wozu „Benutzer 3“ gut war.
• Möglichst geringe Rechte, aber Protect-Lesezugriff: Das Konto muss Protect sehen dürfen, sonst kommen keine Daten an. Alles darüber hinaus – Netzwerkverwaltung, Firmware-Updates – braucht es nicht.
• Keine Zwei-Faktor-Authentifizierung: Für dieses eine Konto darf 2FA nicht aktiv sein. Home Assistant kann keinen zweiten Faktor liefern, der Login schlägt sonst schlicht fehl. Für deinen persönlichen Admin-Account bleibt 2FA selbstverständlich an.
• Starkes, eigenes Passwort: Weil 2FA hier ausfällt, trägt das Passwort die ganze Last – ein langes Zufallspasswort aus dem Passwortmanager.

Und weil wir gerade bei Sicherheit sind: Halte die Konsole aktuell. Wir haben uns die UniFi-Sicherheitslücken 2026 separat angesehen – ein zusätzliches Konto ist nur dann harmlos, wenn das darunterliegende System gepflegt ist.

Schritt 2: API-Schlüssel erzeugen — der Menüpunkt ist umgezogen

Jetzt der Abschnitt, an dem praktisch jede ältere Anleitung im Netz falsch liegt. Der Bereich für API-Schlüssel heißt „Integrations“ und liegt in aktuellen Protect-Versionen im Hauptmenü der linken Seitenleiste (URL-Muster /protect/integrations). Er steckt nicht mehr unter den Einstellungen. Unter Settings findest du inzwischen nur noch General, Intelligence, Evidence Trust, Storage Budgeting und Off-Site Archiving sowie Control Plane und Identity – aber eben keinen Punkt für API-Schlüssel. Wer dort sucht, sucht sich tot und kommt am Ende zu dem Schluss, seine Version könne das nicht. Kann sie doch, sie liegt nur woanders.

So gehst du vor:

1. Öffne UniFi Protect im Browser und melde dich an.
2. Klick in der linken Seitenleiste auf Integrations – im Hauptmenü, nicht in den Einstellungen.
3. Du siehst eine Tabelle mit den Spalten Name, API Key, Type, Created By, Status, Created On, Last Used und Expires. Ist noch kein Schlüssel angelegt, ist sie leer. Darunter steht der Link „Create New API Key“. Rechts findest du außerdem einen Kasten Documentation mit Verweisen auf „Protect API“ und „API Request Format“ – interessant, wenn du später selbst gegen die API programmieren willst.
4. Klick auf Create New API Key. Der Dialog hat drei Felder: Name, Description (Optional) und Expiry (Standard: „Never Expires“), dazu die Buttons Create und Cancel.
5. Vergib einen Namen, an dem du den Schlüssel später wiedererkennst – home-assistant ist eine gute Wahl. In die Beschreibung kannst du reinschreiben, auf welchem Gerät Home Assistant läuft.
6. Beim Ablauf gilt: „Never Expires“ ist bequem, ein Ablaufdatum ist sauberer – aber nur, wenn du dir dazu einen Kalendereintrag machst. Ein unbemerkt abgelaufener Schlüssel bedeutet stumme Kameras und eine unnötig lange Fehlersuche.
7. Klick auf Create – und lies jetzt bitte den nächsten Absatz, bevor du irgendwas anderes anklickst.

Achtung: Der API-Schlüssel wird nur ein einziges Mal im Klartext angezeigt – direkt nach dem Erstellen. Kopiere ihn sofort und leg ihn in deinem Passwortmanager ab. In der Tabelle siehst du danach nur noch einen maskierten Rest. Es gibt keine Funktion, ihn erneut anzuzeigen; wenn er weg ist, bleibt nur, einen neuen zu erzeugen.

Schritt 3: Die Integration in Home Assistant einrichten

Jetzt hast du beides beisammen: einen lokalen Benutzer und einen API-Schlüssel. Wechsel zu Home Assistant und geh auf Einstellungen → Geräte & Dienste → Integration hinzufügen. Such nach „UniFi Protect“. In vielen Netzen taucht die Konsole allerdings schon von selbst als entdecktes Gerät auf – dann klickst du dort einfach auf „Konfigurieren“ und sparst dir die Eingabe von Host und Port.

Als Erstes kommt die Abfrage der Verbindungsart aus dem ersten Abschnitt. Wähl „Lokaler Benutzer und API-Schlüssel (Vollzugriff)“. Danach öffnet sich der Dialog „UniFi Protect-Einrichtung (lokaler Benutzer)“ mit diesen Feldern:

• Host – Hostname oder IP-Adresse deines Protect-Geräts, also der Konsole.
• Port – Standard 443. Den änderst du nur, wenn du die Weboberfläche bewusst umgebogen hast.
• SSL-Zertifikat überprüfen – standardmäßig ausgeschaltet, und das aus gutem Grund: UniFi-Konsolen liefern im lokalen Netz ein selbstsigniertes Zertifikat aus, an dem die Prüfung scheitern würde. Nur wenn du ein eigenes, gültiges Zertifikat hinterlegt hast, kannst du den Schalter einschalten.
• Benutzername – der Name des lokalen Kontos aus Schritt 1, ausdrücklich nicht das Cloud-Konto.
• Passwort – das Passwort dieses lokalen Kontos.
• API-Schlüssel – der Wert aus Schritt 2.

Ja, du brauchst beim Vollzugriff tatsächlich beides: Benutzername plus Passwort und den API-Schlüssel. Das ist kein Fehler im Formular und auch kein Entweder-oder – die Integration nutzt den Benutzer für den klassischen Zugang und den Schlüssel für die neuere Protect-API.

Noch ein Praxishinweis, der später viel Ärger spart: Da du hier die IP-Adresse der Konsole einträgst, sollte diese Adresse fest sein. Vergib im Router eine DHCP-Reservierung für die Konsole, sonst bekommt sie irgendwann nach einem Neustart eine andere Adresse – und Home Assistant meldet plötzlich „nicht erreichbar“, ohne dass du irgendetwas geändert hast. Wie du das sauber aufsetzt, steht in unserem Artikel zum Heimnetzwerk einrichten.

Was danach in Home Assistant auftaucht

Nach einem Klick auf „Senden“ verbindet sich Home Assistant und legt die Geräte an. Was dabei entsteht, hängt stark davon ab, was in deinem Protect-System steckt – grob bekommst du:

• Kameras als camera-Entitäten, in der Regel je Kamera ein hochauflösender Stream und ein Schnappschuss-Eintrag.
• Bewegungs- und Objekterkennung als binary_sensor – also Bewegung erkannt, Person erkannt, Fahrzeug erkannt, Tier erkannt, je nachdem, was die Kamera kann und was du in Protect aktiviert hast. Das sind die Entitäten, aus denen später deine Automationen leben.
• Chimes und Leuchten, falls du eine Türklingel oder einen Floodlight im Einsatz hast – inklusive der Schalter, um sie aus Home Assistant heraus zu steuern.
• Alarmmanager zum Auslösen und Verarbeiten von Protect-Alarmen.
• Diagnose-Sensoren wie Speicherbelegung, freier Platz auf der Festplatte, Laufzeit der Konsole und Verbindungsstatus der einzelnen Kameras.

Wie viele Entitäten am Ende zusammenkommen, hängt komplett an deiner Hardware. Zur Einordnung eine ehrliche Zahl aus unserem Testaufbau: über 130 Entitäten bei 13 Geräten. Nicht alles davon willst du im Dashboard sehen – schalte nach der Einrichtung ab, was du nicht brauchst.

Typische Stolperfallen

Wenn die Einrichtung nicht klappt, liegt es fast immer an einem dieser sechs Punkte:

1. Cloud-Konto statt lokalem Benutzer. Der Klassiker. Deine Ubiquiti-Zugangsdaten funktionieren hier nicht, egal wie oft du sie eintippst. Es muss ein Konto sein, das auf der Konsole selbst angelegt wurde.
2. 2FA am HA-Konto aktiv. Ist für den lokalen Benutzer eine Zwei-Faktor-Authentifizierung eingeschaltet, scheitert der Login – ohne dass die Fehlermeldung besonders deutlich darauf hinweist.
3. Integrations unter Settings gesucht. Der Bereich liegt im Hauptmenü der Seitenleiste. Wenn du unter den Einstellungen nur General, Intelligence, Evidence Trust, Storage Budgeting, Off-Site Archiving, Control Plane und Identity siehst, bist du schlicht an der falschen Stelle.
4. API-Schlüssel nicht notiert. Er ist genau einmal sichtbar. Wer den Dialog schließt, ohne zu kopieren, muss einen neuen Schlüssel anlegen – ärgerlich, aber kein Drama.
5. Die IP der Konsole wechselt. Ohne DHCP-Reservierung ist die Verbindung nur so lange stabil wie das aktuelle Lease.
6. „Nur API-Schlüssel“ gewählt und dann keine Sensoren. Wenn du dich wunderst, wo die Bewegungsmelder geblieben sind: Du hast wahrscheinlich den eingeschränkten Modus erwischt. Integration löschen, neu hinzufügen, diesmal Vollzugriff.

Fazit

Die Verbindung von UniFi Protect und Home Assistant ist in einer Viertelstunde erledigt – vorausgesetzt, du weißt, dass der Bereich „Integrations“ ins Hauptmenü gewandert ist und dass der Vollzugriff sowohl einen lokalen Benutzer als auch einen API-Schlüssel verlangt. Genau an diesen zwei Punkten scheitern die meisten Versuche. Ist die Hürde genommen, bekommst du eine Platin-Integration, die stabil läuft, komplett lokal arbeitet und dir alles liefert, was du für ernsthafte Automationen brauchst.

Der nächste sinnvolle Schritt: Bring die Kameras auf eine eigene Ansicht, statt sie zwischen Lampen und Heizungen zu verstecken – Anregungen dazu findest du in unserem Artikel zum Home-Assistant-Dashboard. In Teil 2 der Serie kümmern wir uns um den SuperLink-Bewegungsmelder und darum, wie er sich in Home Assistant verhält. In Teil 3 geht es um UniFi-Fobs: Wie du einen Tastendruck per Webhook in eine Home-Assistant-Automation verwandelst.

Häufige Fragen

Brauche ich zwingend beides — lokalen Benutzer und API-Schlüssel?

Für den Vollzugriff ja. Der Einrichtungsdialog verlangt Benutzername, Passwort und API-Schlüssel. Nur wenn du dich für „Nur API-Schlüssel“ entscheidest, reicht der Schlüssel allein – dann bekommst du aber ausschließlich Alarmmanager, Kameras mit Streams und Schnappschüssen sowie Leuchten, und keinerlei Sensoren.

Funktioniert mein Ubiquiti-Cloud-Konto?

Nein. Home Assistant sagt das im Dialog ausdrücklich: „Ubiquiti Cloud-Benutzer funktionieren nicht.“ Du brauchst einen lokalen Benutzer, der direkt in deiner UniFi OS Console angelegt wurde. Das gilt auch dann, wenn dein Cloud-Konto Administratorrechte auf der Konsole hat.

Wo finde ich den Integrations-Bereich?

Im Hauptmenü der linken Seitenleiste von UniFi Protect, erkennbar am URL-Muster /protect/integrations. Er lag früher unter den Einstellungen und ist umgezogen – ältere Anleitungen im Netz schicken dich deshalb an die falsche Stelle.

Läuft die Anbindung ohne Internet?

Ja. Home Assistant spricht direkt mit der Konsole in deinem Netz, über Host und Port, mit lokalen Zugangsdaten. Es geht kein Datenverkehr über Ubiquitis Server. Fällt deine Internetverbindung aus, laufen Kameras, Sensoren und Automationen weiter – einer der Hauptgründe, das Ganze überhaupt so aufzubauen.

Was passiert, wenn ich den API-Schlüssel verliere?

Dann kommst du nicht mehr an ihn heran: Er wird nur einmal im Klartext angezeigt, danach siehst du in der Tabelle nur noch einen maskierten Rest. Die Lösung ist unspektakulär – leg im Integrations-Bereich einfach einen neuen Schlüssel an, trag ihn in Home Assistant ein und lösche den alten. Deine Konfiguration, Automationen und Verläufe bleiben dabei unangetastet.