# Authentication

Source: https://developers.weerom.com/docs/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:

```http
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

| 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](https://developers.weerom.com/docs/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](https://developers.weerom.com/docs/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

| 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.
