Codesetup

Der Codesetup-Bereich bildet das Kunden-Onboarding ab (Pairing): codesetup/set erzeugt einen Setup-Code sowie eine Aktivierungs-URL für die Kund:in; codesetup/get liefert nach der Freischaltung durch die Kund:in die individuellen HMAC-Zugangsdaten. Beide Requests werden mit den Partner-HMAC-Zugangsdaten signiert. Der komplette Ablauf ist unter Erste Schritte beschrieben.

Verbindung anfordern (Pairing-Code erzeugen)

POST PARTNER-HMAC /codesetup/set

Schritt 1 des Kunden-Onboardings: Erzeugt einen sechsstelligen Setup-Code sowie die zugehörige Aktivierungs-URL. URL oder Code werden an die Kund:in übermittelt, die die Verbindung in der eBOnaut-App per Link oder manueller Codeeingabe bestätigt. Mit der Aktivierung generiert der Server automatisch die individuellen HMAC-Zugangsdaten (hmac_ID, hmac_secret_key, hmac_encryption_key) der Kund:in und hinterlegt sie im Setup-Eintrag. Der Code ist an den Device-Hash des aufrufenden Systems gebunden und eine Stunde gültig.

Response

Setup-Code und Aktivierungs-URL für die Weitergabe an die Kund:in:

{
  "codesetup_ID": "483920",
  "codesetup_url": "https://app.ebonaut.io/activate/483920"
}

Mögliche Fehler

Code	Meldung	Bedingung
403	access denied	HMAC-Signatur ungültig oder abgelaufen, hmac_unique wiederverwendet oder Origin nicht freigegeben
500	–	Interner Fehler – generische Meldung
503	–	Rate-Limit überschritten (250 Requests/s pro IP)

Zugangsdaten abrufen (Polling)

POST PARTNER-HMAC /codesetup/get/{codesetup_ID}

Schritt 2: Fragt den Status des Setup-Codes ab. Bis zur Aktivierung durch die Kund:in ist regelmäßiges Polling erforderlich (empfohlenes Intervall: 5–10 Sekunden). Der Status 409 signalisiert eine ausstehende Aktivierung. Nach erfolgreicher Aktivierung liefert der Endpunkt einmalig die HMAC-Zugangsdaten der Kund:in – der Eintrag wird anschließend gelöscht. Speichere die Credentials umgehend sicher; ein erneuter Abruf ist nicht möglich.

Pfad-Parameter

Parameter	Beispiel	Beschreibung
codesetup_ID	772622	6-stelliger Setup-Code aus codesetup/set

Response

Die HMAC-Zugangsdaten der Kund:in – einmalig lesbar, danach wird der Eintrag gelöscht:

{
  "hmac_ID": "<22 Zeichen>",
  "hmac_secret_key": "<32 Zeichen>",
  "hmac_encryption_key": "<32 Zeichen>"
}

Feld	Typ	Beschreibung
hmac_ID	string	22-stellige Key-ID – wird in jedem Request als hmac_ID gesendet
hmac_secret_key	string	32-stelliges Secret für die HMAC-SHA256-Signatur
hmac_encryption_key	string	32-stelliger Schlüssel für die AES-256-CBC-Verschlüsselung der message

Mögliche Fehler

Code	Meldung	Bedingung
404	codesetup not found	Code unbekannt oder Device-Hash stimmt nicht mit dem Ersteller überein
410	codesetup expired	Code ist nach einer Stunde abgelaufen – neuen Code per codesetup/set anfordern
409	codesetup data not found	Code existiert, die Aktivierung durch die Kund:in steht noch aus – Polling fortsetzen
406	validationinvalid	codesetup_ID nicht exakt 6 Zeichen
403	access denied	HMAC-Signatur ungültig oder abgelaufen, hmac_unique wiederverwendet oder Origin nicht freigegeben
500	–	Interner Fehler – generische Meldung
503	–	Rate-Limit überschritten (250 Requests/s pro IP)

Gültigkeit der HMAC-Zugangsdaten

Die über codesetup/get bezogenen Kunden-Zugangsdaten sind initial 3 Stunden gültig. Durch den ersten authentifizierten Request mit den neuen Credentials – üblicherweise POST /user/me – wird die Gültigkeit auf 3 Monate verlängert. Jeder weitere erfolgreiche Request erneuert die Gültigkeit erneut auf 3 Monate (rollierend). Ohne diesen ersten Request verfallen die Zugangsdaten nach 3 Stunden.