Authentication
Create an API key, send it with each request and keep it safe.
Hobson authenticates API and MCP requests with workspace API keys.
Create a key
- In Hobson, open Settings › API keys. Only owners and admins can see this page.
- Select Create key, give it a name you'll recognise (for example "Claude Code" or "Order sync") and pick a role.
- Choose when it expires: never, 30 days, 90 days, 1 year or 2 years.
- Copy the key straight away. Hobson shows it once and can't show it again.
Send the key
Send the key in the Authorization header:
Authorization: Bearer YOUR_API_KEYThe REST API also accepts an x-api-key header. The MCP server only reads Authorization, so use that everywhere to keep things simple.
A missing, revoked or expired key gets 401 Unauthorized.
Roles
A key acts with the role you give it, using the same permissions as a teammate with that role.
| Role | What it can do |
|---|---|
| Agent | Approves drafts, replies and picks up handovers |
| Admin | Everything agents do, plus email, settings and the team |
| Viewer | Can read conversations but not reply |
You can't create a key with a higher role than your own. Give each key the lowest role that does the job: a reporting script only needs Viewer.
Rotate a key
Rotating swaps a key's secret without changing anything else. The new key keeps the same name, role and expiry, and still counts as created by whoever made the original.
- In Settings › API keys, open the key's menu and choose Rotate.
- Choose when the old key stops working: Now, 1 hour or 24 hours (the default).
- Copy the new key. It's shown once.
- Update the tool or service that uses the old key.
Until the grace period ends, both keys work and the old key's row says when it stops, for example "Old key stops working at 14:32 tomorrow". Choose Revoke now on that row if you've finished switching over early. The grace period never runs past the key's own expiry.
If you think a key has leaked, rotate it with Now so the old key stops working straight away.
Only owners and admins can rotate keys, and only keys with a role at or below their own. Disabled and expired keys can't be rotated: create a new key instead. An API key can't rotate itself or any other key.
Revoking takes effect straight away. If a teammate leaves the workspace or is moved to a lower role, the keys they created are revoked automatically.
Keep keys secret
- Store keys in a password manager or your tool's secret settings, never in code or a shared document.
- Never put a key in a browser, mobile app or anything a customer can see. Call Hobson from your server.
- If you think a key has leaked, revoke it now and create another.