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.
Speicherung
Abschnitt betitelt „Speicherung“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.
Lebenszyklus
Abschnitt betitelt „Lebenszyklus“| 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/" }}Zuordnung zum Betrieb
Abschnitt betitelt „Zuordnung zum Betrieb“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.
| Recht | Wofür | Endpunkte |
|---|---|---|
day.view | Tag, Tour, Zustellstatus, Unterkünfte und Einstellungen lesen | GET /days/{date}GET /accommodationsGET /accommodations/{id}GET /settings |
job.complete | Lieferung und Abholung als erledigt melden | PATCH /jobs/{id} |
job.order | Reihenfolge der Tour ändern | in v1 noch kein Endpunkt |
booking.view | Buchungen lesen, mit Gastdaten | GET /bookingsGET /bookings/{ref} |
course.view | vermittelte Kurse lesen, ohne die übrigen Buchungen | GET /coursesGET /courses/{uid} |
booking.create | Buchungen anlegen | POST /bookings |
booking.edit | Aufenthalt, Unterkunft, Zimmer und Notizen ändern | PATCH /bookings/{ref} |
booking.cancel | Buchungen stornieren, ohne Geld zu bewegen; zurück zahlt der Admin im Portal | GET /bookings/{ref}/cancel-proposalPOST /bookings/{ref}/cancel |
accommodation.edit | Unterkünfte anlegen, ändern, stilllegen | POST /accommodationsPATCH /accommodations/{id}DELETE /accommodations/{id} |
price.view | Katalog und Preisliste lesen | GET /catalog |
settings.edit | Einstellungen des Betriebs ändern | PATCH /settings |
stats.view | Auswertungen lesen | in 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:
curl "https://skirent.sumware.at/api/ext/v1/bookings" \ -H "Authorization: Bearer $SKI4ME_KEY"const res = await fetch("https://skirent.sumware.at/api/ext/v1/bookings", { headers: { Authorization: `Bearer ${process.env.SKI4ME_KEY}`, },});
const data = await res.json();if (!res.ok) throw new Error(`${data.error.code}: ${data.error.hint}`);console.log(data);import osimport requests
res = requests.get( "https://skirent.sumware.at/api/ext/v1/bookings", headers={"Authorization": f"Bearer {os.environ['SKI4ME_KEY']}"}, timeout=10,)data = res.json()if not res.ok: raise RuntimeError(f"{data['error']['code']}: {data['error']['hint']}")print(data)<?php
$ch = curl_init('https://skirent.sumware.at/api/ext/v1/bookings');curl_setopt_array($ch, [ CURLOPT_RETURNTRANSFER => true, CURLOPT_TIMEOUT => 10, CURLOPT_HTTPHEADER => [ 'Authorization: Bearer ' . getenv('SKI4ME_KEY'), ],]);$body = curl_exec($ch);$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
$data = json_decode($body, true);if ($status >= 400) { throw new RuntimeException($data['error']['code'] . ': ' . $data['error']['hint']);}print_r($data);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/" }}Ausgeschlossene Rechte
Abschnitt betitelt „Ausgeschlossene Rechte“| 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. |
Protokollierung im Journal
Abschnitt betitelt „Protokollierung im Journal“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.
Umgang mit dem Geheimnis
Abschnitt betitelt „Umgang mit dem Geheimnis“- 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.