deCONZ REST API für Anfänger: erste Requests, Auth und typische Fehler

Wenn du bei deCONZ zum ersten Mal mit der REST API arbeitest, landest du fast immer sofort in zwei klassischen Fehlermeldungen: unauthorized user und link button not pressed. Genau das habe ich heute im lokalen Lab einmal sauber nachgebaut – inklusive Container-Setup, API-Tests und Screenshot der Phoscon-Oberfläche.

Der Artikel hier ist also keine bloße Zusammenfassung der Doku, sondern basiert auf einem echten lokalen Test mit deCONZ im Container.

Wofür die deCONZ API überhaupt gut ist

Die deCONZ REST API ist die Schnittstelle, über die du dein Zigbee-Setup automatisieren kannst. Darüber liest du zum Beispiel Lampen, Sensoren und Gruppen aus oder schaltest Geräte direkt per HTTP an. Wenn du parallel die Hersteller-Doku offen haben willst, ist die offizielle Phoscon-/ConBee-Dokumentation die richtige Referenz.

Spannend ist das vor allem dann, wenn du deCONZ nicht nur per App bedienen willst, sondern mit Home Assistant, eigenen Skripten oder kleinen Automationen arbeitest. Falls du dein Smart Home gerade erst aufbaust, schau zuerst in meinen Überblick zu Smart Home für Einsteiger. Wenn du später alles zentral bündeln willst, passt auch mein Guide zu Home Assistant auf Proxmox.

Mein Test-Setup im Lab

• deCONZ als lokaler Container
• Phoscon-Weboberfläche unter /pwa/index.html
• REST-Test per curl
• eigener Screenshot der laufenden UI

Eine kleine Stolperfalle kam direkt am Anfang: Mein Lab-Mapping war falsch. deCONZ lauscht im Container auf Port 80 und nicht auf 8080. Mit einem Mapping wie 8080:8080 wirkt der Dienst kaputt, obwohl deCONZ intern längst läuft. Korrekt war in meinem Test:

-p 8080:80
-p 8443:443

Das ist genau die Art Fehler, die in Tutorials gerne fehlt, obwohl sie Einsteiger unnötig Zeit kostet.

Erster Check: Läuft die Oberfläche überhaupt?

Nach dem korrigierten Port-Mapping war die Phoscon-Oberfläche im Browser sofort erreichbar. Der Root-Pfad leitete bei mir auf /pwa/index.html weiter. Genau das willst du sehen, bevor du überhaupt mit API-Calls anfängst.

Für den Praxischeck reicht dieser Schritt schon: Wenn die Oberfläche sauber lädt und GET /api antwortet, steht die Basis für die ersten Requests.

Der erste API-Call: Warum deCONZ erst einmal „unauthorized user“ zurückgibt

Der erste naive Test ist fast immer dieser hier:

curl http://localhost:8080/api

In meinem Test kam genau diese Antwort zurück:

[{"error":{"address":"/","description":"unauthorized user","type":1}}]

Das ist kein kaputtes Setup, sondern erwartetes Verhalten. deCONZ will zuerst einen autorisierten API-User. Ohne diesen Key kommst du an die eigentlichen Geräte- und Gruppen-Endpoints nicht sinnvoll heran.

API-Key anlegen: der zweite typische Fehler

Der nächste Schritt ist normalerweise ein POST auf /api, zum Beispiel so:

curl -H "Content-Type: application/json" \
  -d '{"devicetype":"highenddigital#labtest"}' \
  http://localhost:8080/api

Auch das habe ich direkt getestet. Die Antwort war:

[{"error":{"address":"/","description":"link button not pressed","type":101}}]

Auch diese Meldung ist normal. Sie bedeutet: deCONZ akzeptiert die Erstellung eines neuen API-Users erst, wenn du in Phoscon den Kopplungsmodus beziehungsweise die Freigabe aktivierst. Genau daran scheitern viele beim ersten Versuch – und halten die API fälschlich für defekt.

Was du daraus praktisch mitnehmen solltest

• HTTP erreichbar, aber API blockt: Das ist bei deCONZ am Anfang normal.
• type:1 heißt: dir fehlt die Autorisierung.
• type:101 heißt: du musst den Link-Button bzw. die API-Freigabe erst aktivieren.
• Falsches Port-Mapping kann den Eindruck erzeugen, dass deCONZ gar nicht läuft.

Wenn du also gerade an deinem ersten Skript sitzt, prüfe zuerst diese Reihenfolge:

1. Ist die Phoscon-Oberfläche erreichbar?
2. Ist das Port-Mapping korrekt?
3. Bekommst du bei GET /api die erwartete Unauthorized-Antwort?
4. Hast du vor dem POST /api die Freigabe in Phoscon aktiviert?

Minimaler Docker-Start, der im Test funktioniert hat

Wenn du deCONZ schnell lokal ausprobieren willst, reicht für den Anfang schon ein sehr kleines Setup. In meinem Test lief dieser Start sauber genug für UI und erste API-Checks:

docker run -d \
  --name lab-deconz \
  -p 8080:80 \
  -p 8443:443 \
  -e DEBUG_INFO=1 \
  deconzcommunity/deconz:latest

Wichtig ist wieder der erste Port: außen 8080, innen 80. Genau da lag bei mir der vermeidbare Fehler.

Die ersten sinnvollen Endpoints nach erfolgreicher Freigabe

Sobald dein API-User angelegt ist, musst du nicht planlos herumprobieren. Diese drei Endpoints sind für den Einstieg meistens die sinnvollsten:

• GET /api/<apikey>/config – prüft, ob dein API-Key sauber funktioniert
• GET /api/<apikey>/lights – zeigt deine Lampen
• GET /api/<apikey>/sensors – zeigt Taster, Bewegungsmelder und andere Sensoren

Mein Rat: Erst config, dann lights, dann sensors. So findest du API- oder Pairing-Probleme deutlich schneller, als wenn du sofort mit Schreibbefehlen auf Gruppen oder Szenen losgehst.

Typische Anfängerfehler mit deCONZ API

• Port verwechselt: deCONZ läuft intern nicht auf 8080.
• Phoscon erreichbar, API trotzdem gesperrt: Das ist normal, solange noch kein API-User angelegt wurde.
• Zu früh an eigenen Skripten zweifeln: Oft ist nicht das Skript kaputt, sondern schlicht die Freigabe fehlt.
• UI und API gedanklich vermischt: Phoscon ist die Oberfläche, deCONZ REST API ist die technische Schnittstelle darunter.

deCONZ oder direkt Home Assistant?

Wenn du einfach nur Geräte koppeln und solide steuern willst, ist deCONZ mit Phoscon für viele immer noch angenehm zugänglich. Wenn du dagegen sehr schnell in komplexere Automationen, Dashboards und zentrale Logik willst, ist Home Assistant meist der nächste sinnvolle Schritt.

Genau deshalb finde ich die Kombination interessant: deCONZ für das Zigbee-Gateway, Home Assistant für die eigentliche Orchestrierung. Den Unterbau dafür zeige ich in meinem Artikel zu Home Assistant auf Proxmox.

Für wen sich deCONZ heute noch lohnt

Ich finde deCONZ immer noch interessant, wenn du einen soliden Zigbee-Einstieg mit Phoscon-Oberfläche willst und nicht alles direkt in YAML, MQTT oder tieferer Bastel-Logik aufziehen möchtest. Für viele ist das der angenehmere Mittelweg zwischen App-Komfort und eigener Automation.

Wenn du noch die passende Hardware suchst, ist ein ConBee III Zigbee USB-Gateway der naheliegende Startpunkt für genau dieses Setup.

Mein Fazit

Der wichtigste Punkt aus meinem Test ist ziemlich simpel: Wenn deCONZ läuft, aber deine ersten API-Calls Fehler liefern, ist das meistens kein echter Fehler, sondern der normale Onboarding-Zustand. unauthorized user und link button not pressed gehören bei den ersten Requests praktisch dazu.

Genau deshalb lohnt es sich, die Oberfläche, das Port-Mapping und den ersten Auth-Flow sauber zu prüfen, bevor du an irgendwelchen Skripten zweifelst.

Hinweis: Die Produktlinks sind Affiliate-Links. Wenn du darüber kaufst, bekomme ich eine kleine Provision. Für dich bleibt der Preis gleich.