Authentication
/ How a request gets authorized, and what happens when it does not.
API key (server-to-server, custom UI)
Create a key in Dashboard, then Settings, then API keys. It is shown once. Store it server-side. Never ship it in client-side code.
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 | Frontier plan or higher (apiAccess capability) |
Browser origin (widget, hosted link)
The widget and hosted Link call the same endpoints with no API key. Authorization comes from the request Origin header instead, checked against the agent's allowed-domains list (Dashboard, then Widget settings). That path is for the hosted surfaces only. Build your own integration on an API key.
Auth error responses
| Status | Meaning |
|---|---|
| 401 | Missing or invalid API key, or no Origin header and no key |
| 403 | Key valid but the plan lacks API access, or the origin is not on the allowed-domains list |