API-Referenz

Authentifizierung & Token

Geräteanmeldung und Token. Nach der Anmeldung müssen token und c-id zur selben Sitzung gehören.

Anmeldeablauf für Geräte

Client
https://<host>:<port>/init
Server

POST /init

HTTP request

c-id: clientId · body: empty

Feld mit der Maus oder durch Antippen öffnen
1 / 7

sessionKey = Base64Decode(token). Beim Login auf beiden Seiten abgeleitet; nicht als Bearer senden. logout oder revokeSession widerruft die Sitzung, eine Passwortänderung nicht.

In der Geräte-App unter Verbindungen → API-Tokens erstellen. clientId und token gemeinsam kopieren. Zum Widerrufen löschen. Bearer nur über HTTPS senden.

HTTP-Body-Verschlüsselung schützt nicht den geladenen Webcode. Beim ersten Zugriff ist eine vertrauenswürdige Serveridentität nötig. Im Browser vertrauenswürdiges HTTPS verwenden.

Bei zu vielen gleichzeitigen nicht authentifizierten Verbindungen antwortet der Server vor dem WebSocket-Upgrade mit HTTP 429 und leerem Body. Versuchen Sie es später erneut.

WebSocket /auth · AuthErrorCode · Fehler

Erster Frame: 10 s. Danach 60 s für den Handshake. Login und Freigabe insgesamt: 300 s.

INVALID_LOGIN_REQUEST
Prüfen Sie die Anmeldeanfrage und starten Sie einen neuen Handshake.
PASSWORD_SETUP_REQUIRED
Legen Sie zuerst ein Anmeldepasswort auf dem Gerät fest.
INVALID_PASSWORD
Passwort prüfen und erneut versuchen.
PEER_IDENTITY_CHANGED
Geräteidentität vor dem Fortfahren prüfen.
REMOTE_ACCESS_DISABLED
Fernzugriff auf dem Gerät aktivieren.
REJECTED
Der Gerätebesitzer hat die Anmeldung abgelehnt.
TIMEOUT
Eine neue Anmeldung starten.
TOO_MANY_LOGIN_ATTEMPTS
Vor dem nächsten Versuch warten.

Operationen

http

Bearer-API-Token

JSON mit einem separaten API Token über HTTPS senden, ohne den Anfrage-Body zu verschlüsseln.

bash
curl --request POST \
  --url 'https://<device-host>:<https-port>/graphql' \
  --header 'c-id: <client-id>' \
  --header 'Authorization: Bearer <api-token>' \
  --header 'Content-Type: application/json' \
  --data '{"query":"{ app { deviceName capabilities access } }"}'
mutation

logout

Widerruft die aktuelle authentifizierte Sitzung des aufrufenden Clients.

graphql
mutation logout {
  logout
}