Authentication & scopes
Bearer API keys, least-privilege scopes, and how to keep them safe.
Authenticate every request with an API key in the Authorization header:
Authorization: Bearer wo_live_xxxxxxxxxxxxxxxxxxxxA missing or invalid key returns 401. A valid key that lacks the scope an endpoint requires returns 403 with the missing scope named.
Scopes
Keys are least-privilege — grant only what an integration needs:
records:read — list and read work orders · records:write — create and update work orders · proof:read — read verifiable trust proofs · assets:read / assets:write — read / manage assets · locations:read, departments:read, categories:read, vendors:read, users:read — reference data · webhooks:manage — manage webhook subscriptions.
Keeping keys safe
The plaintext key is shown only once, at creation — we store only a hash and can never show it again. Keep keys server-side (never ship them in a browser or mobile app), store them in a secret manager, scope them narrowly, and rotate by creating a new key and revoking the old one under Admin → API keys. Keys can be given an expiry date at creation.