Authentication
Every request carries an API key as a bearer token:
Authorization: Bearer amb_live_<key>A key in a query string is refused with 400: URLs end up in logs.
API keys
Section titled “API keys”Dispatchers create keys in Instellingen → Koppelingen. A key:
- belongs to the company, not to the person who made it, so it keeps working when they leave
- has a name, a set of scopes and an expiry date (one year by default)
- is shown once, when it’s created. Ambula stores only its hash
- stops working within 60 seconds of being revoked
Keys start with amb_live_ in production and amb_test_ in the sandbox, so a secret scanner can find a leaked one.
Scopes
Section titled “Scopes”| Scope | Grants |
|---|---|
<resource>:read |
Reading a resource, for example rides:read or conversations:read |
<resource>:write |
Creating, changing and deleting it, for example rides:write |
recordings:read |
Call recordings |
messages:send |
Sending WhatsApp messages |
webhooks:manage |
Webhook endpoints and the events feed |
Give each integration only the scopes it uses. A BI export needs :read scopes only.
Refused requests
Section titled “Refused requests”| Status | code |
When |
|---|---|---|
401 |
unauthenticated |
The key is missing, unknown, expired or revoked |
403 |
insufficient_scope |
The key lacks a scope. The error names it |
403 |
module_disabled |
The resource belongs to a module your company doesn’t have: contacts, opdrachten, runaways or insights |
404 |
not_found |
The record doesn’t exist, or belongs to another company |
A record of another company answers 404, never 403, so ids can’t be probed.