All Admin API requests are authenticated with an organization-scoped API key passed as a Bearer token.
Bearer token
Authorization: Bearer YOUR_API_KEY
The key fully determines which organization the request can read. There is no organization or location parameter; a key can only ever access its own organization's data.
If the header is missing, malformed, expired, or the key has been revoked:
- Status:
401 Unauthorized - Body:
{ "error": { "code": "unauthorized", "message": "Invalid or missing API key" } }Permissions
Each key reads only what it was granted. Every endpoint needs one permission:
| Permission | Grants |
|---|---|
orders:read | GET /orders, GET /orders/{id} |
bookings:read | GET /bookings, GET /bookings/{id} (and the /appointments paths) |
stays:read | GET /stays, GET /stays/{id} |
tickets:read | GET /tickets, GET /tickets/{id} |
customers:read | GET /customers, GET /customers/{id} |
events:read | GET /events |
customer_data:read | Adds customer and billing personal data to what the other permissions return |
user_data:read | Adds staff members' names and emails to what the other permissions return |
customer_data:read and user_data:read open no endpoint of their own. They
widen every response the key can already read: see
Conventions → Customer privacy for the fields.
No response names staff members yet, so user_data:read adds nothing today.
A request to an endpoint the key lacks the permission for returns
403 forbidden, naming the missing permission (see
Errors). Keys created before permissions existed
keep the access they had: every endpoint, without personal data.
Key management
Organization owners and admins manage keys under Settings → API keys
(/settings/api):
- Create a key and choose its permissions. The full secret is shown once, at creation. Store it immediately; it cannot be retrieved later (we keep only a hashed digest).
- Edit a key's name and permissions. The change applies from the key's next request; the secret stays the same.
- Rotate a key. Creates a replacement secret with the same permissions and keeps the old key valid for a grace window (24 hours by default), so you can swap without downtime, then it expires automatically.
- Revoke a key. Takes effect immediately on the next request.
Keys are secret
Admin API keys are always secret keys, prefixed admin_sk_…. They grant
server-to-server read access to your organization, so keep them server-side
and never expose one in a browser.
There is no publishable Admin API key. Publishable keys are a Storefront API
concept, and Storefront API keys (store_pk_… and store_sk_…) are not
accepted here: presenting one returns 401 unauthorized
(see Errors).
Security recommendations
- Grant each key only the permissions its integration uses, and
customer_data:readoruser_data:readonly where personal data must be shared. - Treat keys as secrets; keep them server-side and out of client JavaScript.
- Use HTTPS exclusively.
- Roll keys on a schedule and immediately if you suspect exposure.
