Authentication
How a request gets authorized, and what happens when it does not.
API key (server-to-server)
Generate an API key on the MCP page.
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) |
MCP OAuth
Remote MCP in Cursor, Claude, and VS Code uses OAuth. Add https://app.humaner.io/api/mcp with no headers. Sign in once. A hu_ API key still works on that endpoint for scripts and CI.
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. |