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
- Sign in to My Playrooms.
- Open API keys in your account.
- 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.
| Operation | Permission |
|---|---|
| Search playrooms, read playroom details and booking options | none, 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 returns403. - 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.