Skip to Content
Developers

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_3f9a1c2e5b7d4a68c0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5

A 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

KindStarts withWhere to use itWhat it may do
Readwo_live_On a serverRead everything the API has: the shop, services, staff, free times, customers, bookings and payments.
Writewo_live_On a serverRead everything, and make, move and cancel bookings and change customers.
Publicwo_pub_In a web page or an app, where anyone can read itRead 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

  1. Sign in to the shop's WeerOm admin as an administrator. Other roles cannot make or remove keys.
  2. Open Settings, then Features, then Connections.
  3. Under "What will use the key", give it a name that says where it goes, such as "Billit" or "Booking page".
  4. 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.
  5. 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

StatuscodeWhat happenedWhat to do
401missing_keyNo Authorization: Bearer header.Send the header, with Bearer, a space and the key.
401invalid_keyWeerOm knows no such key.Check that you copied the whole key.
401revoked_keySomeone at the shop removed the key.Ask the shop for a new one.
403plan_requiredThe shop is not on the Premium plan.Ask the shop to move to Premium. The same key works again from then on.
403key_not_allowedThe 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.

On this page