Authentication
Every request is authenticated with a per-account API key in the X-Api-Key header.
Every request carries your key in the X-Api-Key header. There is no OAuth flow and no session cookie — a key is the whole credential.
X-Api-Key: onb_live_<key_id>_<secret>Key shape#
A key is the prefix onb_live_ followed by a 16-character hex id, an underscore, then a 64-character hex secret. The id half is public (it identifies which key made a request in your dashboard); the secret half is shown to you exactly once and is never stored in recoverable form on our side.
Getting a key#
In the dashboard: /settings/integrations → API keys (inbound) → Create key. Copy it from the one-time "API key — copy it now, it won't be shown again" panel. Revoke a key from the same list at any time; you may hold up to 5 active keys, and issuing new ones is itself rate-limited to 10/hour per account. Creating or revoking a key needs the owner or admin team role, unless your account is not in a team.
What a key can do#
A key acts as you
Anyone holding your key can do through this API whatever your team role allows — for a recruiter or above, create candidates on your account and, on any request that asks for it, send WhatsApp messages as you. Store it like a password and revoke it immediately if it leaks. When you create a key you can choose Read only — it may call every GET and is refused with 403 and code: "key_read_only" on every other verb — and an expiry of 30, 90 or 365 days (default: never; every earlier key is Full access and never expires). An expired key gets the same 401 as an unknown key. A full key is limited by your team role.
Every write (each POST, PATCH and DELETE) checks the team role of the key’s user at the time of the request, not when the key was created. An owner, admin or recruiter in a team, or an account not in a team, can write. A viewer’s key is refused with 403 Your team role doesn't allow this. Ask your team's admin or owner., and so is any key whose account or team record could not be read at that moment (retry that one). Reads (GET) are not role-checked.
Failure modes#
A missing header, a malformed key, an unknown key, a wrong secret, a revoked key and an expired key ALL return the identical 401 Unauthorized. This is deliberate — a response that told you "this key id exists but the secret is wrong" would let a caller enumerate live keys. If you get a 401, check the header is present and the whole key was copied correctly; there is nothing more specific to diagnose from the response alone.
A 503 This resource is temporarily unavailable. Try again shortly. means the service could not check your key at all — retry shortly. It says nothing about your key and is never a reason to rotate it.
- Always call over HTTPS.
- Never put your key in a URL (query string) — headers only.
- A
404with an EMPTY body on every path (rather than any of the shapes above) means this API is switched off for this deployment, not that your key is wrong.