# Keys and allowed websites

> Publishable and secret keys, what each one may do, live and test keys, and the websites a publishable key may be used from.

A key does two things: it says which project is asking, and it bounds what the
caller may do. There are two kinds, and each can be live or test.

## Publishable and secret

| | Publishable `pk_` | Secret `sk_` |
|---|---|---|
| Read services, staff, free times and published pages | yes | yes |
| Take a booking, and read, move, cancel or pay for one with its token | yes | yes |
| List bookings | no | yes |
| Read payments, or start any other checkout | no | yes |
| Belongs in a web page | yes | never |

A publishable key is in the page source of every website using it, so it may
only do what any visitor could: read what is published, and take a booking
within the limits on one visitor. A secret key can read every customer's name
and every payment, so it lives in server code and environment settings, and
nowhere a browser can read it.

> [!WARNING]
> Building a client with a secret key where a `window` exists throws, so the
> mistake fails on your own machine rather than in somebody's network tab.

## Live and test

Test keys read what live ones do, and also what you are still trying out, so a
staging site shows a change before any customer meets it:

- Every page as its draft was last saved, published or not. Anybody who can
  open a site using a test key can read that unpublished work.
- A service or a person added while the dashboard is in test mode. They are
  test only, offered to test keys and to no customer, until you make them live,
  and they keep their id when you do.
- Booking rules changed while the dashboard is in test mode. They are a test
  copy that test keys are held to, until you apply it to live or discard it.

Opening hours, dates and time off are the same for both: they are the real
diary.

What test keys book or pay is test data, kept apart from live data, so you can
try a whole website before any customer uses it:

- A test booking never takes a slot from a customer, and it is only offered
  times the real diary has free, so a test behaves the way a customer would.
- Its emails go to the account's own address, marked as a test, never to the
  address typed into the booking.
- It is paid through the project's test payments, set up from the payments
  screen while the dashboard is in test mode. They run at your provider's test
  mode: test card numbers, and nothing real is charged. Until they are set up,
  a test booking takes no payment.
- Its events reach your test webhook endpoints, never your live ones.
- A test key's web analytics hits are counted and listed on the Tracking
  screen, from your own machine too, and never become figures.

Test data appears in the dashboard while it is in test mode, and never in the
overview, reports or traffic figures, which count live data only. It is
deleted after 30 days, or at once from the API keys screen.
Calls made with a test key count against the month's allowance like any other.

A test publishable key may also go without allowed websites, and may send a
customer back over http after paying, so it works from your own machine.

## Allowed websites

A publishable key can carry a list of the websites it may be used from. A
browser says which page a request comes from, and a key used from a website
that is not on its list is refused with `origin_not_allowed`.

Write each website the way a browser sends it: the scheme and the host, and a
port if it has one, with no path and no trailing slash.

```text
https://salon.example
https://www.salon.example
```

The dashboard does not create a live publishable key without at least one
website, since such a key works from anybody's page. It is a guard on browsers
only: anything that is not a browser can say it comes from any address it
likes, which is why a publishable key may only do harmless things in the first
place.

## Keeping keys

A key is shown once, when it is made, and kept only in a form it cannot be
recovered from. A lost key is replaced, never looked up. A project can hold
25 keys in use at once; a revoked key stops working
immediately and no longer counts.