API keys let other software read and write your organization's data through the SERVOS API: an integration pulling bookings and revenue, or your own website selling from your catalog. You create them under Settings → API Keys (owners and admins). How to use the API itself is in the API docs.
Two kinds of key
- "Admin API" keys give server-to-server access to bookings and revenue. They are always secret.
- "Storefront API" keys give catalog and cart access for customer-facing
apps. Choose "Publishable" for a key that's safe to embed in a browser or
mobile app (it starts with
store_pk), or "Secret" for one that stays on your server (store_sk).
Creating a key
Press Create key in the right section and give the key a "Name" that says what uses it ("Marketing site"). Storefront keys open a dialog where you also pick the type; admin keys open a page where you also choose what the key can read. The full key is shown once, in "Copy your API key". Copy it somewhere safe before pressing Done. After that only the last characters are visible; nobody, SERVOS included, can recover it.
The table shows each key's name, mask, "Last used", "Created", and status: "Active", "Expiring", "Expired", or "Revoked". Admin keys also show their "Access".
Choosing what an admin key can read
An admin key reads only what you set to Read in the table on its page. Everything starts at None. The resources are grouped: "Sales" holds "Orders", "Stays", "Bookings" and "Tickets"; "Operations" holds "Customers" and "Change feed"; "Personal data" holds "Customer data" and "User data". Hover the question mark next to a resource to see what it covers. The toggle on a group's own row sets every resource in it at once, and shows no choice while the group is mixed. Grant at least one resource from "Sales" or "Operations", and only what the integration needs.
"Personal data" widens everything else the key reads. Without "Customer data", the integration sees customers only as an id that doesn't say who they are. With it, it also gets customers' names, emails, phone numbers and company details, and the billing address on each order. "User data" is for your staff members' names and emails; nothing the API returns names staff yet, so it adds nothing today. Set either to Read only for an integration you're allowed to share those details with. Keys with either show a "Personal data" badge in the table.
To rename a key or change its access later, choose Edit in its menu. The change applies to the integration's next request, and the key itself stays the same. Keys created before permissions existed can read everything except personal data.
Rotating and revoking
Rotate creates a replacement with the same permissions and gives the old key a grace period, from immediately to 7 days (default 24 hours), to update your integration before it stops. Revoke stops a key at once and can't be undone. Keys that are no longer active can be deleted from the list.
Common questions
I lost the key. Rotate it, or revoke it and create a new one. There is no way to see it again.
Which key goes on our website? A Storefront "Publishable" key for anything that runs in the visitor's browser. Keep secret keys on your server only.
Does a key expire by itself? No. Only rotation sets an expiry on the old key.
