Zum Inhalt springen

Einstieg

Schlüssel und Rechte

Angemeldet wird mit einem Schlüssel, den ein Admin des Betriebs im Portal unter Schnittstelle anlegt. Niemand muss dafür etwas freischalten.

Ein Schlüssel ist ein Paar aus einer öffentlichen Kennung und einem Geheimnis.

Teil Beispiel
Kennung 0193f2a7-4c31-7b8e-9d02-5f1a2b3c4d5e bleibt im Portal sichtbar
Geheimnis skr_9dLp2Qx7Vn4Rk0TzYb8HsWc3Mf6JgA1uEe5oNiXqPl einmal sichtbar, beginnt mit skr_

Gesendet wird beides zusammen in einem Kopf, getrennt durch einen Punkt:

Authorization: Bearer 0193f2a7-4c31-7b8e-9d02-5f1a2b3c4d5e.skr_9dLp2Qx7Vn4Rk0TzYb8HsWc3Mf6JgA1uEe5oNiXqPl

Der Anfang skr_ ist Absicht: ein Scanner erkennt daran ein Geheimnis, das versehentlich in einem Repository gelandet ist.

Nur einen SHA-256 des Geheimnisses, dazu die letzten vier Zeichen zum Wiedererkennen in der Liste. Wer eine Sicherungskopie in die Hand bekommt, hat damit keinen Zugang.

Das Geheimnis erscheint genau einmal, direkt nach dem Anlegen. Danach gibt es keinen Weg, es wieder zu sehen. Wer es verliert, legt einen neuen Schlüssel an und widerruft den alten.

Die aufrufende Adresse wird nicht gespeichert. Vermerkt wird, wann der Schlüssel zuletzt benutzt wurde, höchstens einmal je Minute.

Zustand Wie er entsteht
gültig Ein Admin legt ihn an.
abgelaufen Das Ablaufdatum ist überschritten. Der Schlüssel gilt bis zum Ende des eingetragenen Tages. Ohne Datum läuft er nicht ab.
widerrufen Ein Admin widerruft ihn. Der Eintrag bleibt stehen, damit das Journal lesbar bleibt.

Ein falscher, ein abgelaufener und ein widerrufener Schlüssel bekommen dieselbe Antwort. Sie sagt nicht, welcher der drei Fälle vorliegt.

Antwort401Unauthorized

{
"error": {
"code": "unauthorized",
"message": "Der Schlüssel gilt nicht.",
"status": 401,
"hint": "Im Portal unter Einstellungen, Schnittstelle, einen gültigen Schlüssel anlegen.",
"documentation_url": "https://skirent.sumware.at/api/"
}
}

Fehlt der Kopf ganz, nennt der Hinweis die erwartete Form:

Antwort401Unauthorized

{
"error": {
"code": "unauthorized",
"message": "Dieser Weg braucht einen Schlüssel.",
"status": 401,
"hint": "Authorization: Bearer <kennung>.<geheimnis> senden. Die Beschreibung steht unter /api/ext/openapi.json.",
"documentation_url": "https://skirent.sumware.at/api/"
}
}

Der Host der Anfrage wird unter /api/ext nicht gelesen. Erreichbar ist die Schnittstelle unter der Adresse der Plattform, https://skirent.sumware.at, nicht unter der Domain des Betriebs.

Ist ein Betrieb gesperrt, abgelaufen oder archiviert, antwortet die Schnittstelle wie seine Website: wer nicht ausliefert, liefert auch keine Daten aus.

Der Schlüssel gehört dem Betrieb und nicht der Person, die ihn angelegt hat. Er bleibt gültig, wenn diese Person das Unternehmen verlässt.

Beim Anlegen wählt der Admin die Rechte einzeln. Ein Schlüssel für das Hotel liest den Zustellstatus, ein Schlüssel für die Skischule liest Kurse, und keiner von beiden sieht mehr als das.

RechtWofürEndpunkte
day.viewTag, Tour, Zustellstatus, Unterkünfte und Einstellungen lesenGET /days/{date}GET /accommodationsGET /accommodations/{id}GET /settings
job.completeLieferung und Abholung als erledigt meldenPATCH /jobs/{id}
job.orderReihenfolge der Tour ändernin v1 noch kein Endpunkt
booking.viewBuchungen lesen, mit GastdatenGET /bookingsGET /bookings/{ref}
course.viewvermittelte Kurse lesen, ohne die übrigen BuchungenGET /coursesGET /courses/{uid}
booking.createBuchungen anlegenPOST /bookings
booking.editAufenthalt, Unterkunft, Zimmer und Notizen ändernPATCH /bookings/{ref}
booking.cancelBuchungen stornieren, ohne Geld zu bewegen; zurück zahlt der Admin im PortalGET /bookings/{ref}/cancel-proposalPOST /bookings/{ref}/cancel
accommodation.editUnterkünfte anlegen, ändern, stilllegenPOST /accommodationsPATCH /accommodations/{id}DELETE /accommodations/{id}
price.viewKatalog und Preisliste lesenGET /catalog
settings.editEinstellungen des Betriebs ändernPATCH /settings
stats.viewAuswertungen lesenin v1 noch kein Endpunkt

job.order und stats.view lassen sich schon vergeben, in der Fassung v1 gibt es aber noch keinen Endpunkt, der sie verlangt.

Fehlt ein Recht, ist die Antwort 403 und nennt das fehlende Recht beim Namen:

Terminal-Fenster
curl "https://skirent.sumware.at/api/ext/v1/bookings" \
-H "Authorization: Bearer $SKI4ME_KEY"

Antwort403Forbidden

{
"error": {
"code": "forbidden",
"message": "Diesem Schlüssel fehlt: booking.view.",
"status": 403,
"hint": "Im Portal unter Einstellungen, Schnittstelle, einen Schlüssel mit diesem Recht anlegen.",
"documentation_url": "https://skirent.sumware.at/api/"
}
}
Recht Warum nicht
Rückzahlung Geld zurück bewegt Geld nach draußen. Das bleibt bei einem Menschen mit Anmeldung im Portal. Ein Schlüssel storniert deshalb nur; die Rückzahlung steht danach offen an der Buchung.
Personal verwalten Ein Schlüssel, der Personal einladen darf, könnte sich selbst vermehren.
Preise ändern Eine falsche Preisliste aus einem fremden Programm fällt erst beim Gast auf, und dann steht der Preis schon in einer Buchung.
Journal lesen Das Journal nennt Namen von Mitarbeitern. Es ist ein Nachweis für den Betrieb, nicht für seine Partner.

Jede Änderung über die Schnittstelle steht im Journal des Betriebs, wie jede andere auch. Der Handelnde ist der Schlüssel, mit Kennung und Namen:

actor       key:01a1c478-a2b4-734d-827a-e37fd88d51e7
actor_name  Hotel Alpenhof

Geben Sie einem Schlüssel deshalb den Namen des Systems, das ihn benutzt. Im Ernstfall beantwortet das Journal damit die Frage, wer eine Buchung geändert hat, und womit.

  • Ein Schlüssel je System. Dann lässt sich einer widerrufen, ohne die anderen stillzulegen.
  • Nur die Rechte, die das System braucht.
  • Das Geheimnis gehört in die Umgebung oder in einen Tresor, nicht in den Quelltext und nicht in ein Programm, das im Browser läuft.
  • Ein Ablaufdatum für alles, was nur eine Saison lang gebraucht wird.