Authentifizierung
Partnerschlüssel, die sechsundzwanzig Berechtigungen, was eine Zuweisung bedeutet und wie Sie ohne Ausfallzeit rotieren.
Jede Anfrage an die Partner-API führt genau einen Zugangsschlüssel mit, an der üblichen Stelle:
Authorization: Bearer brp_<prefix>.<secret>
Es gibt kein anderes Verfahren. Kein Schlüssel im Query-String, keine Basic
Auth, kein Cookie. Eine Anfrage ohne diesen Header oder mit einem fehlerhaften
Wert antwortet 401, bevor irgendetwas anderes ausgewertet wird.
Was ein Schlüssel ist
Ein Schlüssel hat zwei Hälften, getrennt durch einen Punkt.
| Hälfte | Was sie ist | Wo sie auftauchen darf |
|---|---|---|
brp_<prefix> | Eine öffentliche Kennung des Schlüssels. | Ihre Logs, eine Support-E-Mail, die Schlüsselliste auf dieser Website. |
<secret> | 256 Bit Zufall. | Ihr Secret Manager und der Authorization-Header. |
BackResto speichert das Präfix und einen geschlüsselten Digest des Secrets. Das Secret selbst wird nicht gespeichert und kann nicht wiederhergestellt werden — nicht von Ihnen, nicht vom Support, nicht aus der Datenbank. Geht es verloren, widerrufen Sie den Schlüssel und erstellen einen neuen.
Zuweisungen: Restaurant × Berechtigung
Ein Schlüssel ist kein „Konto mit Rechten“. Er ist eine Liste ausdrücklicher Zuweisungen, jede davon ein Paar:
Es gibt sechsundzwanzig Berechtigungen, und ihre Systematik lohnt sich einmal zu lernen:
| Berechtigung | Gewährt Zugriff auf |
|---|---|
deliveries:read | Die Endpunkte für die Lieferliste und für die Lieferdetails. |
delivery-images:read | Die Fotos, die an einer Lieferung hängen. |
<collection>:read | Eine der vierundzwanzig Collections — cooling:read, temperature-records:read, traceability-labels:read und so weiter, eine Berechtigung pro Collection. |
Jede Berechtigung endet auf :read. Es gibt keine Partner-Berechtigung, die
schreibt, und es kann auch keine geben: Die schreibende Seite dieser API gehört
der BackResto-App, und ein Partnerschlüssel ist strukturell außerstande, eine
solche zu halten.
Ein Schlüssel mit deliveries:read auf restaurant-1 und restaurant-2 und
delivery-images:read nur auf restaurant-1 liest Fotos für das erste
Restaurant und bekommt 403 für das zweite. Das ist eine unterstützte
Konfiguration und kein Fehler — manche Integrationen wollen die Datensätze ohne
die Bilder.
Fragen Sie nach dem, was Sie nutzen. Sechsundzwanzig Berechtigungen sind keine Speisekarte zum Abhaken: Das Restaurant liest die Liste, bevor es ihr zustimmt, und eine Anfrage nach allem braucht länger, bis sie durch ist, als eine Anfrage nach den vier Collections, die Ihr Produkt tatsächlich liest.
Drei Fehlerfälle, bewusst voneinander getrennt:
404— der Schlüssel hat für dieses Restaurant überhaupt keine Zuweisung. Die API verrät einem unbefugten Aufrufer nicht, ob ein Restaurant existiert.403— der Schlüssel hat eine Zuweisung für dieses Restaurant, aber nicht die Berechtigung, die dieser Endpunkt braucht.401— unter anderem ein Schlüssel, der gar keine Zuweisung mehr hat. Ein Schlüssel, dem die letzte Zuweisung genommen wurde, authentifiziert nicht mehr, statt leer zu antworten.
Um zu sehen, was ein Schlüssel tatsächlich hält, fragen Sie ihn:
GET /v1/restaurants listet die Restaurants mit ihren Berechtigungen, und
GET /v1/restaurants/{id}/collections listet die
Collections, die er öffnet.
Wer einen ausstellen kann
Wir, auf Anfrage, und nur für Restaurants, die zugestimmt haben. Unter Einen Schlüssel erhalten steht, was Sie senden und was zurückkommt.
Zuweisungen werden festgelegt, wenn der Schlüssel eingerichtet wird, und nur durch eine weitere Anfrage geändert. Es gibt keinen Weg — weder für Sie noch für uns — der einen Schlüssel erweitert, ohne dass das Restaurant erneut zustimmt.
Ablauf und Widerruf
Ein Schlüssel läuft nicht von selbst ab, es sei denn, Sie haben um einen solchen gebeten. Er bleibt gültig, bis er widerrufen wird.
Der Widerruf wirkt sofort: Die nächste Anfrage mit diesem Schlüssel antwortet
401, dieselbe Antwort, die ein unbekannter oder abgelaufener Schlüssel bekommt.
Er lässt sich nicht rückgängig machen, und das muss er auch nicht — ein Ersatz
ist ein neuer Schlüssel, kein wiederhergestellter.
Rotieren ohne Ausfallzeit
Eine Integration kann zwei aktive Schlüssel gleichzeitig halten, ein Schlüsselwechsel braucht also kein Wartungsfenster. Bitten Sie uns um einen Wechsel, läuft er in dieser Reihenfolge ab:
- Wir stellen einen zweiten Schlüssel mit denselben Restaurants und Berechtigungen aus.
- Sie rollen das neue Secret aus und sagen uns, wenn es überall aktiv ist.
- Wir prüfen, dass der alte Schlüssel nicht mehr benutzt wird — wir sehen, wann sich jeder Schlüssel zuletzt authentifiziert hat, und das ist das Signal, das Schritt 4 sicher macht.
- Wir widerrufen den alten.
Rotieren Sie nach einem Zeitplan, den Sie selbst wählen, und stellen Sie die Anfrage ein paar Tage bevor der alte Schlüssel weg sein soll: Die Schritte 2 und 3 müssen Sie und wir miteinander abstimmen, und der ganze Sinn der Reihenfolge oben ist, dass nie etwas auch nur kurz tot ist.
Hygiene
- Speichern Sie ihn sofort nach Erhalt und löschen Sie die E-Mail. Danach
existiert das Secret an genau zwei Stellen: in Ihrem Secret Manager und im
Authorization-Header. - Ein Schlüssel pro Deployment, nicht einer pro Unternehmen. Ein geleakter Staging-Schlüssel sollte nie ein Produktionsvorfall sein, und ein Widerruf sollte nie mehr lahmlegen als das, was geleakt ist.
- Senden Sie uns niemals das Secret — nicht in einem Ticket, nicht um einen Schlüssel zu benennen. Das öffentliche Präfix benennt ihn eindeutig und darf überall stehen.
- Achten Sie in Ihrem eigenen Monitoring auf
401. Ein Schlüssel, der zu scheitern beginnt, wurde widerrufen, und die Antwort darauf ist ein Gespräch, keine Retry-Schleife.