Authentifizierung & Rechte

Ein Schlüssel je Stadt und Anwendung, mit genau den Rechten, die diese Anwendung braucht.

Schlüssel senden

Der Schlüssel gehört in den Header Authorization — nicht in die Query-Parameter, weil er sonst in Server-Logs, Proxys und Referrern landet.

AnfrageShell

curl -sS \
  -H "Authorization: Bearer rb_live_a1b2c3d4e5f60718_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  https://rufbusle.de/api/v1/me

Ein Schlüssel hat die Form rb_live_<kennung>_<geheimnis>. Die Kennung ist öffentlich und steht auch in der Schlüsselliste im Admin — daran erkennen Sie, welcher Schlüssel gerade im Einsatz ist, ohne das Geheimnis zu kennen.

Die Stadt hängt am Schlüssel

Deshalb gibt es in der ganzen API keinen Stadt-Parameter.

Andere Bereiche von RufBusle tragen die Stadt im Pfad. Die öffentliche API nicht: der Mandant wird beim Prüfen des Schlüssels festgelegt und danach auf jede einzelne Abfrage angewendet. Ein Schlüssel kann damit auch bei einem Programmierfehler keine Daten einer fremden Stadt liefern.

Wer mehrere Städte anbindet, verwaltet mehrere Schlüssel — und weiß an der Kennung immer, welche Stadt gerade antwortet.

Rechte (Scopes)

Nichts ist pauschal freigeschaltet. Jeder Schlüssel trägt genau die Rechte, die ihm zugeteilt wurden.

read:scheduleFahrplan lesen: Haltestellen, Linien, Fahrten und Bedienzeiten.
read:bookingsBuchungen lesen (pseudonymisiert): Buchungen ohne personenbezogene Angaben — keine Namen, keine Telefonnummern.
read:bookings:piiBuchungen inkl. Kontaktdaten lesen: Zusätzlich Telefonnummern der Fahrgäste. Nur vergeben, wenn ein Auftragsverarbeitungsvertrag mit dem Empfänger besteht.
read:vehiclesFahrzeuge lesen: Fahrzeug-Stammdaten inkl. Kennzeichen und Fremdsystem-ID.
write:bookingsBuchungen anlegen und stornieren: Fahrten im Namen von Fahrgästen buchen und stornieren (zusätzlicher Buchungskanal). Die übermittelte Telefonnummer erhält die Buchungsbestätigung; zurücklesen lässt sie sich nur mit read:bookings:pii.

Welcher Endpunkt braucht welches Recht

/api/v1/meVerbindungstest: Jeder gültige Schlüssel genügt.
/api/v1/stopsHaltestellen: Erfordert read:schedule.
/api/v1/linesLinien: Erfordert read:schedule.
/api/v1/tripsFahrten: Erfordert read:schedule.
/api/v1/bookingsBuchungen: Erfordert read:bookings.
/api/v1/bookingsBuchung anlegen: Erfordert write:bookings.
/api/v1/bookings/{id}/cancelBuchung stornieren: Erfordert write:bookings.
/api/v1/vehiclesFahrzeuge: Erfordert read:vehicles.
/api/v1/feed/gtfs.zipGTFS-Feed: Erfordert read:schedule.

Wenn die Anmeldung scheitert

Drei Fälle, die leicht verwechselt werden.

401 UNAUTHENTICATEDSchlüssel greift nicht: Fehlt, ist falsch geschrieben, wurde widerrufen, ist abgelaufen oder die Stadt ist deaktiviert. Wir unterscheiden diese Fälle in der Antwort bewusst nicht — sonst ließe sich damit ausprobieren, welche Schlüssel existieren.
403 INSUFFICIENT_SCOPERecht fehlt: Der Schlüssel ist gültig, trägt aber nicht das für diesen Endpunkt nötige Recht. Die Stadt kann es im Admin nachtragen.
403 NOT_ENTITLEDTarif enthält die API nicht: Der Schlüssel ist gültig und hat das Recht, aber der Tarif der Stadt umfasst die offenen Schnittstellen nicht. Das ist keine technische, sondern eine vertragliche Frage.

Schlüssel wechseln

Ohne Ausfallfenster, weil mehrere Schlüssel gleichzeitig gelten dürfen.

1. Zweiten Schlüssel mit denselben Rechten anlegen.
2. Neues Geheimnis in Ihrem System hinterlegen und ausrollen.
3. In der Schlüsselliste prüfen, ob der alte Schlüssel noch benutzt wird — die Spalte „zuletzt verwendet“ zeigt es.
4. Alten Schlüssel widerrufen.

Widerrufene Schlüssel werden nicht gelöscht, sondern bleiben als Eintrag bestehen. So lässt sich später nachvollziehen, welcher Zugang wann bestand.

Schlüssel senden#

Die Stadt hängt am Schlüssel#

Rechte (Scopes)#