Skip to main content

API authentication

API keys​

Booking endpoints require an active API key in the raw X-API-Key header:

curl -H "X-API-Key: YOUR_API_KEY" \
https://api.my-playrooms.de/v1/orders/ORDER_ID

Use the header directly. The public API does not use Authorization: Bearer tokens. Playroom catalog and booking-option reads are available without a key.

Creating a key​

  1. Sign in to My Playrooms.
  2. Open API keys in your account.
  3. Create a key and store it immediately; it is shown only once.

Ownership and security​

  • Orders created with a key belong to that key's account.
  • An API key cannot read another account's order.
  • Each key has its own permissions (see below). There are no general Read/Write/Admin scopes.
  • Use one key per integration and revoke keys that are exposed or no longer needed.

Key permissions​

Each key carries only the permissions you assign to it. Assign the minimum your integration needs.

OperationPermission
Search playrooms, read playroom details and booking optionsnone, no key required
Create a booking (POST /v1/orders)Create bookings (bookings.create)
Read a booking (GET /v1/orders/{orderId})Read bookings (bookings.read)
Create a payment session (POST /v1/orders/{orderId}/payment)Create payment links (bookings.payment.create)
  • Change permissions under API keys > Edit. The page shows Permissions (assigned) and Effective permissions (what the key can use right now).
  • A key can never do more than your account can. If your account is locked or deleted, the key stops working at once; if you regain access, the assigned permissions become effective again.
  • A missing, invalid or revoked key returns 401. A valid key without the required permission returns 403.
  • Keys created before permissions were introduced keep all three permissions until you edit them.
  • Regenerating a key replaces the secret and keeps its permissions.

Safe retries when creating bookings​

Send an Idempotency-Key header with every POST /v1/orders so that a retry never creates a second booking.

  • Same key and same request after a completed booking: you receive the original order ID.
  • A request that was rejected before any booking existed (for example because the playroom is not available) can be retried with the same key.
  • Same key with a different request, or a request that was interrupted before the booking was confirmed: 409. Contact support before retrying with a new key.