Guides
Authentication, keys and scopes
Every request carries a bearer key. Keys are created in Utilitay Account, under your organisation’s Developers tab. One product per key. Scopes and instance reach are fixed when the key is created; 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: a key in a query string is not read. The key is shown once, when it is made.
Scopes
Scopes name the wire, not the pack. A key with subjects:write can create memberships in a Political party instance and students in a High school one.
contacts:readList and read people and links
contacts:writeCreate, update, deactivate people; create links
subjects:readList and read memberships
subjects:writeCreate, update, deactivate memberships
events:readList and read events and event types
events:writeRecord and void events
messages:readRead the messages rules produced
groups:readList and read groups and who is in them
groups:writeCreate, update, deactivate groups; add and remove members
sends:readList and read sends, and preview who one reaches
sends:writeWrite, edit, publish and call off plain-text sends. Publishing spends the budget
sends:write spends money. A key with it can publish plain-text sends by SMS and email, which spends the instance’s budget. Give it only to a system that writes messages itself; one that records events needs events:write, and your rules do the sending. GET /messages stays read only.