Authentication
How a request gets authorized, and what happens when it does not.
API key (server-to-server)
Generate an API key under /integrations if you're on Custom or Humaner.
Authorization header
Authorization: Bearer hm_live_xxxxxxxx| Property | Value |
|---|---|
| Format | hm_live_ prefix, plus a random token |
| Storage | SHA-256 hash, server-side. The raw key cannot be recovered |
| Scope | Bound to one organization, checked against the agent on every request |
| Requires | Custom or Humaner (apiAccess capability) |
Browser origin (widget, hosted link)
The widget and hosted link call the same endpoints. Authorization comes from the request Origin header instead, checked against the agent's allowed-domains list you can enter (in Widget settings).
Auth error responses
| Status | Meaning |
|---|---|
| 401 | Missing or invalid API key, no origin header or no Agent ID found. |
| 403 | Key valid but do not have access to, or the origin isn't an allowed domain. |