Guides
Authentication, keys and scopes
Every request carries a bearer key, made in Utilitay Account under your organisation's Developers tab. One product per key: a Menu key opens Menu paths only. Scopes and the businesses a key reaches are fixed when it is made; roll or revoke the key to change them.
Key anatomy
utl_live_k3Jh9QpL2mZx7VbN4cRt8WyS1dFg6HaU0eIo5PqA3zK1a2B3c
Prefix
utl_live_ · identifies the key type
Body
43 random characters
Checksum
6 characters · catches typos before a request
Send it as Authorization: Bearer utl_live_…, in the header only. The key is shown once, when it is made. Whatever the key does is recorded against it by name — a request it approves says decided_by_name: "API key · Front desk" — so name keys for the system that holds them.
Scopes
requests:readList and read requests, with their answers and history
requests:writeCancel, reschedule and reassign requests. The customer is told
decisions:writeApprove and decline requests that wait. The customer is told, and gets their code
verifications:writeCheck a customer's code; a right one closes the request
customers:readList the phones that made requests, and their names
menus:readList the business's menus and whether each is published
decisions:write and requests:write reach customers. Each approve, decline, cancel or move is told to the customer where the business has linked Raven. A system that only shows the inbox needs requests:read alone; a counter that checks codes needs verifications:write and nothing else.