Pairing-Ablauf

Bevor deine Anwendung im Namen einer Kund:in handeln darf, muss die Kund:in die Verbindung freigeben. Das nennen wir Pairing. Diese Seite zeigt den Ablauf auf einen Blick.

Die zwei Zugangsdaten-Sätze

	Partner-Zugangsdaten	Kunden-Zugangsdaten
Wer stellt sie aus?	eBOnaut, einmalig an dich als Partner:in	Der Server, automatisch bei der Aktivierung durch die Kund:in
Wofür?	Nur für codesetup/set und codesetup/get	Für alle übrigen Endpunkte
Wie viele?	Ein Satz pro Partner:in	Ein Satz pro angebundener Kund:in
Bestandteile	hmac_ID, secret_key, encryption_key	hmac_ID, hmac_secret_key, hmac_encryption_key

Ablauf

 Deine Anwendung                eBOnaut API                    Kund:in (eBOnaut-App)
       |                             |                                 |
       |-- 1. codesetup/set -------->|                                 |
       |   (Partner-HMAC)            |                                 |
       |<-- Code + Aktivierungs-URL -|                                 |
       |                             |                                 |
       |-- 2. URL oder Code an die Kund:in weitergeben -------------->|
       |                             |                                 |
       |-- 3. codesetup/get -------->|          4. Kund:in öffnet URL |
       |<-- 409 (noch nicht aktiv) --|<-------- oder gibt Code ein ----|
       |         ... alle 5-10 s ... |          und bestätigt          |
       |                             |   Server erzeugt Kunden-HMAC    |
       |-- codesetup/get ----------->|                                 |
       |<-- 200 + Kunden-HMAC -------|    (einmalig lesbar!)           |
       |                             |                                 |
       |-- 5. user/me -------------->|                                 |
       |   (Kunden-HMAC)             |                                 |
       |<-- Profil, Gültigkeit 3 Mon.|                                 |
       |                             |                                 |
       |-- weitere Requests (Kunden-HMAC) ---------------------------->|

Die Endpunkte

• POST /codesetup/set erzeugt Code und Aktivierungs-URL. Gib beides an die Kund:in weiter, zum Beispiel per E-Mail, in deiner Oberfläche oder als QR-Code.
• POST /codesetup/get/{code} fragst du alle 5 bis 10 Sekunden ab: 409 heißt, die Kund:in hat noch nicht bestätigt, 200 liefert die Zugangsdaten.
• POST /user/me ist der erste Request mit den neuen Zugangsdaten und verlängert deren Gültigkeit.

Speichere die Zugangsdaten sofort sicher, sie sind nur einmal abrufbar.

Gültigkeit und Fristen

Was	Frist	Wenn abgelaufen
Pairing-Code	1 Stunde	410, neuen Code mit codesetup/set erzeugen
Kunden-Zugangsdaten vor dem ersten Request	3 Stunden	403, Pairing wiederholen
Kunden-Zugangsdaten nach dem ersten Request	3 Monate ab dem letzten erfolgreichen Request (rollierend)	403, Pairing wiederholen
Verbindung von der Kund:in gelöscht (mein.ebonaut.de)	sofort	403, Kund:in muss erneut freigeben

Häufige Fragen

Was, wenn ich die Zugangsdaten nicht gespeichert habe? Starte das Pairing neu, die Kund:in bestätigt erneut.

Wie sperre ich einen Zugang? Über hmac/delete. Danach ist der Zugang sofort ungültig und ein neues Pairing nötig.

Kann die Kund:in die Verbindung selbst beenden? Ja, jederzeit. Siehe Zugang & Nutzungsregeln.

Muss jede Kund:in einzeln verbunden werden? Ja. Pro Kund:in gibt es einen eigenen Satz Zugangsdaten. Speichere die Sätze getrennt und wähle bei jedem Request den passenden aus.