Authentication
The three kinds of key, where a shop makes them, what 401 and 403 mean, and how to keep a key safe.
Every request carries a key in the Authorization header:
GET /v1/payments HTTP/1.1
Host: api.weerom.com
Authorization: Bearer wo_live_1_3f9a1c2e5b7d4a68c0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5A key is a prefix, the shop's number, _ and 48 hex characters. It belongs to one shop and works on that shop only.
Three kinds of key
| Kind | Starts with | Where to use it | What it may do |
|---|---|---|---|
| Read | wo_live_ | On a server | Read everything the API has: the shop, services, staff, free times, customers, bookings and payments. |
| Write | wo_live_ | On a server | Read everything, and make, move and cancel bookings and change customers. |
| Public | wo_pub_ | In a web page or an app, where anyone can read it | Read the shop, its services, its staff and its free times, and make a booking under a visitor's limits. It reads no customer and no booking. |
Pick the kind with the least it needs. An invoicing sync reads, so it gets a read key. A booking page in the browser gets a public key. A chat assistant that books from your server gets a write key.
A key of the wrong kind answers 403 key_not_allowed. A public key that asks for /customers gets it, and so does a read key that sends POST /bookings. The API reference names the kinds each endpoint takes.
Public keys
A public key opens what a visitor to the shop's own site already sees. A booking made with it is a visitor's booking:
- The shop's rules apply, as on its own booking form, and the key may not send
"as": "staff". - The same limits as the shop's form apply: per address, per phone number, per email, and 4 open bookings from one address. Over them, the answer is 429
limit_reached.
All requests from a server come from one address, so a public key on a server would hit the limit per address quickly. A server uses a write key. Build a booking page covers both.
Make a key
- Sign in to the shop's WeerOm admin as an administrator. Other roles cannot make or remove keys.
- Open Settings, then Features, then Connections.
- Under "What will use the key", give it a name that says where it goes, such as "Billit" or "Booking page".
- Under "What it may do", pick Read for a read key, Read and change for a write key, or Take bookings from a web page for a public key.
- Copy the key. The admin shows it once. WeerOm stores a hash of the key, not the key, so nobody can show it again later.
The shop must be on the Premium plan. A shop holds up to 10 working keys. Make one key for each tool, so you can remove one without breaking the others.
Keep a key safe
A read or write key reads every customer's name, email and phone number. Treat it like a password.
- Keep it in an environment variable or your platform's secret store. Leave it out of source code and out of Git.
- Call the API from your server. A
wo_live_key in a web page or a mobile app is a key anyone can read. - If a key leaks, remove it and make a new one.
A public key may sit in a page. The worst a stranger can do with it is what they could do on the shop's own booking form.
Remove a key
Remove a key in the same place you made it: Settings, Features, Connections. It stops working at once and every request with it answers 401 with the code revoked_key.
When a key fails
| Status | code | What happened | What to do |
|---|---|---|---|
| 401 | missing_key | No Authorization: Bearer header. | Send the header, with Bearer, a space and the key. |
| 401 | invalid_key | WeerOm knows no such key. | Check that you copied the whole key. |
| 401 | revoked_key | Someone at the shop removed the key. | Ask the shop for a new one. |
| 403 | plan_required | The shop is not on the Premium plan. | Ask the shop to move to Premium. The same key works again from then on. |
| 403 | key_not_allowed | The key works, but its kind may not call this endpoint. | Use a key of the kind the endpoint takes. Ask the shop for one. |
A 401 answer also carries WWW-Authenticate: Bearer realm="WeerOm API".
A shop that leaves Premium keeps its keys. They answer 403 until the shop is on Premium again, and then they work without a change on your side.
Stop on a 401
Do not retry a request that failed with 401. The answer will not change, and an address that sends 60 requests without a working key within 10 minutes gets 429 before WeerOm looks at the key.