Authentifizierung
Bearer-Keys pro Organisation und Umgebung, mit klar abgegrenzten Scopes.
Jeder Request an die Partner-API trägt einen API-Key als Bearer-Token:
Authorization: Bearer hs_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
Requests ohne gültigen Key werden mit 401 beantwortet.
Key-Format
| Bestandteil | Bedeutung |
|---|---|
hs_live_ / hs_test_ |
Umgebung: Production bzw. Sandbox (QA) |
| Präfix (erste 16 Zeichen) | dient der Identifikation, z. B. in Übersichten — der Rest wird niemals angezeigt |
| Rest | zufälliges Secret |
Hemostat speichert Keys ausschließlich als Hash. Der Klartext-Key existiert nur einmal: in dem Moment, in dem er erstellt und Ihnen übermittelt wird. Er kann später weder von Hemostat noch über die API erneut abgerufen werden. Geht ein Key verloren, wird er ersetzt.
Behandeln Sie Keys wie Passwörter: nur serverseitig verwenden, nie in Client-Code, Apps, Repositories oder Logs. Bei Verdacht auf Kompromittierung den Key umgehend über Hemostat widerrufen lassen.
Widerruf und Ablauf
- Keys können jederzeit widerrufen werden (derzeit durch Hemostat, auf Ihre Anforderung). Ein widerrufener Key wird sofort abgewiesen.
- Keys können mit einem Ablaufdatum versehen sein. Nach Ablauf
antwortet die API mit
401. - Erstellung und Widerruf werden auditiert.
Scopes
Jeder Key trägt eine Menge von Scopes, die festlegt, was er darf:
| Scope | Berechtigung |
|---|---|
orders:read |
Aufträge und deren Event-Historie lesen |
orders:write |
Aufträge anlegen und stornieren |
webhooks:manage |
Webhook-Endpoints verwalten |
Ein Request, dessen Key den nötigen Scope nicht trägt, wird mit 403
abgelehnt. Fordern Sie nur die Scopes an, die Ihre Integration
tatsächlich braucht.
Weitere Statuscodes im Auth-Kontext
| Status | Bedeutung |
|---|---|
401 |
Key fehlt, ist ungültig, widerrufen oder abgelaufen |
403 |
Key gültig, aber Scope fehlt — oder die Organisation ist gesperrt |
402 |
Schreibzugriffe sind wegen offener Zahlungen vorübergehend blockiert |
Die genauen Fehler-Codes je Endpoint stehen in der API-Referenz; das Antwortformat ist unter Aufträge → Fehlerformat beschrieben.