Getting started

Scopes and restrictions

A key does only what it was made to do, on only the lines and desks it was given.

The four scopes#

When the owner makes a key they tick what it may do. A key holds at least one scope, and can be edited later without changing the key itself.

Scopes
Scope	Lets the key	Endpoints
`read`	Read the business, its lines, services, desks and visits. Every GET.	`GET /business` `GET /lines` `GET /lines/{lineId}` `GET /services` `GET /desks` `GET /visits` `GET /visits/{visitId}`
`visits:write`	Add a visit, change its note or urgency, mark it urgent, cancel it, put it back in the line.	`POST /visits` `PATCH /visits/{visitId}` `POST /visits/{visitId}/urgent`
`desks:operate`	Call the next person to a desk, call a visit to a desk, serve, complete, mark a no-show, and start, pause or end a desk's shift.	`POST /desks/{deskId}/call-next` `PUT /desks/{deskId}/status` `POST /visits/{visitId}/transitions`
`lines:manage`	Make a line, replace its settings, pause it and resume it.	`PUT /lines` `PUT /lines/{lineId}` `POST /lines/{lineId}/pause` `POST /lines/{lineId}/resume`

Scopes do not include each other: a key with desks:operate alone can call people but cannot list visits. A request outside the key's scopes is answered 403, and the message names the scope it needed:

Response (403)

{
  "error": {
    "code": "FORBIDDEN",
    "message": "This API key does not have the desks:operate permission"
  }
}

Transitions take the scope of where they go#

POST /v1/visits/{visitId}/transitions moves a visit along one edge, and what it needs depends on to. What a desk does needs desks:operate; taking someone out of the line or putting them back needs visits:write.

The scope each transition needs
`to`	Needs	What it does
`called`	`desks:operate`	Call it to the desk in deskId
`in_progress`	`desks:operate`	Start serving
`completed`	`desks:operate`	Complete
`no_show`	`desks:operate`	Mark a no-show
`cancelled`	`visits:write`	Cancel — take it out of the line
`queued`	`visits:write`	Put it back in the line

Limiting a key to some lines#

A key can be given all lines (the default) or a list of them. A key limited to some lines works as if the others did not exist:

GET /v1/lines, GET /v1/services and GET /v1/visits list only its lines;
a desk is listed if it calls from one of its lines, and a desk's lineIds show only those;
a line, visit or service on another line is answered 404, for a read and for a write alike — never 403, which would say it exists;
it cannot make a new line (PUT /v1/lines is 403): the line it made would not be one of its own, and it could never see it again.

A line that is removed from the business drops out of every key's list by itself. Webhook endpoints have a line filter of their own, set on the endpoint — see Choosing events and lines.

Limiting a key to some desks#

A key can also be given a list of desks. That limits what it does at a desk, which is what desks:operate is for:

GET /v1/desks lists only its desks;
calling next, setting a desk's status, or calling a visit to a desk outside its list is a 404;
serving, completing or marking a no-show a visit that is at another desk is a 404 — the key cannot finish somebody else's customer.

A desk outside the key's list (404)

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Desk not found"
  }
}

Lines and desks combine: a key limited to the X-ray line and the X-ray counter can act only there, however many other lines and desks the business has.

Worked examples#

Keys for common jobs
What it is for	Scopes	Lines and desks
A lobby screen showing who is called	`read`	All lines, all desks — or the lines of that waiting room
A booking page on your website that adds walk-ins	`read`, `visits:write`	Only the lines you offer online
A call-next button at Room 1	`desks:operate`	Room 1's desk only
Keeping a CRM in step, with a nightly check	`read`	All lines
Clinic software that runs the whole day	`read`, `visits:write`, `desks:operate`	All lines, all desks
A script that sets up lines each season	`read`, `lines:manage`	All lines (a key limited to some lines cannot make one)

The call-next button is the example to copy: a key on a device on a desk can be lost with the device, so it can do one thing at one desk, and revoking it stops nothing else.