Zum Hauptinhalt springen

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​

  1. Melde dich bei My Playrooms an.
  2. Öffne API-Schlüssel in deinem Konto.
  3. 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.

VorgangBerechtigung
Playrooms suchen, Details und Buchungsoptionen lesenkeine, 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 liefert 403.
  • 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.