API-Authentifizierung
API-Keys
Buchungsendpunkte benötigen einen aktiven API-Key im Header X-API-Key:
curl -H "X-API-Key: YOUR_API_KEY" \
https://api.my-playrooms.de/v1/orders/ORDER_ID
Der öffentliche API-Vertrag verwendet keinen Authorization: Bearer-Token. Playroom-
Katalog und Buchungsoptionen können ohne Schlüssel gelesen werden.
Key erstellen
- Melde dich bei My Playrooms an.
- Öffne API-Schlüssel in deinem Konto.
- Erstelle einen Schlüssel und speichere ihn sofort; er wird nur einmal angezeigt.
Besitz und Sicherheit
- Mit einem Schlüssel erstellte Buchungen gehören zum Konto des Schlüssels.
- Ein API-Key kann nicht auf die Buchung eines anderen Kontos zugreifen.
- Jeder Schlüssel hat eigene Berechtigungen (siehe unten). Allgemeine Read/Write/Admin-Scopes gibt es nicht.
- Verwende pro Integration einen eigenen Schlüssel und widerrufe offengelegte Schlüssel sofort.
Schlüssel-Berechtigungen
Ein Schlüssel hat nur die Berechtigungen, die du ihm zuweist. Vergib nur das, was deine Integration braucht.
| Vorgang | Berechtigung |
|---|---|
| Playrooms suchen, Details und Buchungsoptionen lesen | keine, kein Schlüssel nötig |
Buchung erstellen (POST /v1/orders) | Buchungen erstellen (bookings.create) |
Buchung lesen (GET /v1/orders/{orderId}) | Buchungen lesen (bookings.read) |
Zahlungs-Session erstellen (POST /v1/orders/{orderId}/payment) | Zahlungslinks erstellen (bookings.payment.create) |
- Ändere die Berechtigungen unter API-Schlüssel > Bearbeiten. Die Seite zeigt Berechtigungen (zugewiesen) und Wirksame Berechtigungen (was der Schlüssel jetzt tatsächlich nutzen kann).
- Ein Schlüssel kann nie mehr als dein Konto. Ist dein Konto gesperrt oder gelöscht, funktioniert der Schlüssel sofort nicht mehr; bei erneutem Zugriff werden die zugewiesenen Berechtigungen wieder wirksam.
- Ein fehlender, ungültiger oder widerrufener Schlüssel liefert
401. Ein gültiger Schlüssel ohne die nötige Berechtigung liefert403. - Schlüssel, die vor Einführung der Berechtigungen erstellt wurden, behalten alle drei Berechtigungen, bis du sie bearbeitest.
- Beim Neu-Generieren wird das Geheimnis ersetzt, die Berechtigungen bleiben.
Sichere Wiederholung beim Erstellen von Buchungen
Sende bei jedem POST /v1/orders den Header Idempotency-Key, damit eine Wiederholung nie eine zweite Buchung erzeugt.
- Gleicher Schlüssel und gleiche Anfrage nach abgeschlossener Buchung: du erhältst die ursprüngliche Bestell-ID.
- Eine Anfrage, die abgelehnt wurde, bevor eine Buchung existierte (zum Beispiel weil der Playroom nicht verfügbar ist), kann mit demselben Schlüssel wiederholt werden.
- Gleicher Schlüssel mit anderer Anfrage oder eine Anfrage, die vor der Bestätigung abgebrochen wurde:
409. Wende dich an den Support, bevor du mit einem neuen Schlüssel wiederholst.