Skip to main content
Hobbes authenticates server-to-server requests with organization-scoped API keys. Keys begin with hb_live_ and should be handled like passwords.

​
Send a key

Use a Bearer authorization header:
If your integration cannot set a Bearer header, use x-api-key instead:
Do not send both. Bearer authentication takes precedence when both are present.

​
Choose scopes

Create separate keys for separate integrations. A warehouse export does not need transcript access, and a transcript processor does not necessarily need account or metrics access. Optional scopes are not added to existing keys automatically. Create or rotate to a key that explicitly carries the minimum required scopes. Keep Playbook access separate from production publishing when possible. A key with playbook:write can update staging without changing the production agent. Add agent:publish only when the integration must publish after an explicit confirmation and successful conversation tests.
Transcript text can contain prospect PII. Enable transcripts:read only for systems that need raw text and apply your normal retention and access rules.

​
Rotate a key

  1. Create a replacement key with the same minimum scopes.
  2. Deploy the replacement to your integration.
  3. Confirm successful requests with the replacement key.
  4. Revoke the old key in Hobbes.
Revocation takes effect immediately. Keep the old key active only for the short overlap required to complete the deployment.

​
Authentication failures

Hobbes returns the same organization-safe 404 for resources that do not exist and resources owned by another organization.