Keys and requests
How to authenticate, what a key may do, limits, request ids and test 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
Authorization: Bearer <your key>
Content-Type: application/json
X-Request-Id: your-own-id
- Only the
Authorizationheader is read. A key in the address is ignored. X-Request-Idis optional: letters, numbers,.,_and-, up to 100 characters. Every answer carries arequest_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.