Docs
View as Markdown

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

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.