# Keys and requests

> How to authenticate, what a key may do, limits, request ids and test keys.

Source: https://docs.orkero.app/keys

## Your keys

When you are set up you receive a **test key** and, when you are ready, a **live key**. Each
key is shown once: keep it on your server, never in a web page or an app.

| Key | What happens |
| --- | --- |
| Test | Checked exactly like a live key. Nothing is kept, booked or emailed, and the answer says `"test": true`. |
| Live | Real bookings, real questions to real patients. |

Keys start `vl_test_` and `vl_live_` today. They will start `ork_test_` and `ork_live_` once
the new address is live; existing keys keep working.

A key says what it may do (its **scopes**) and which practices it covers. Ask for a
replacement at any time: the old key keeps working for a day so you can change over.

| Scope | Lets you |
| --- | --- |
| `booking.read` | See the visits a practice offers online and its free times |
| `booking.write` | Book, look up, move and cancel bookings your key made |
| `feedback.signals` | Tell us a visit is done |
| `feedback.figures` | Read the Net Promoter Score |
| `feedback.events` | Ask for feedback events |
| `accounts.feed` | Read each day's accounts figures |
| `accounts.tally` | Read the tally between companies |
| `payroll.hours` | Read each person's hours for a pay period |

## Every request

```http
Authorization: Bearer <your key>
Content-Type: application/json
X-Request-Id: your-own-id
```

- Only the `Authorization` header is read. A key in the address is ignored.
- `X-Request-Id` is optional: letters, numbers, `.`, `_` and `-`, up to 100 characters.
  Every answer carries a `request_id` (yours, or one we made). Quote it to support.
- There are no CORS headers: call the API from your server.

## Limits

60 requests a minute and 10,000 a day per key, unless agreed otherwise. Over a limit the
answer is `429` with a `Retry-After` header in seconds. Thirty wrong keys in ten minutes
from one address and that address is told to wait.

## Sending the same thing twice

Booking requests carry your own `request_id`; a visit carries your own `visit_id`. Send the
same one again after a timeout and it is done once, with `"duplicate": true` in the answer.
It is always safe to retry.

## Versions

Today there is one version, `v1`, in the address. Dated versions chosen with an
`Orkero-Version` header are coming; the version you start on stays yours until you choose to
move. See the [Changelog](/changelog).
