Make a key
HeadHoncho API keys are made in the app, at Automations, then API keys: https://app.headhoncho.app/automations/api. Only a person signed in to the workspace can make one.
- Open Automations, then API keys, and choose to make a key.
- Name it for what will use it, such as "Reporting laptop". The name shows in the job history of anything it changes.
- Pick the companies it reaches. It sees no others.
- Set its access for each area, at read or do.
- Under Advanced, turn on "hide personal details" if the key should not see who the customers are. It is off unless you turn it on.
- Make the key and copy it. It looks like
hh_live_...and is shown once.
Access per area
A key holds each area at read or do. Read lets it look. Do lets it change things as well. A call that needs do on an area the key holds only at read is refused with `read_only`, and a call to an area the key does not hold is refused with `no_access`.
| Area | In the key as | Read lets it call | Do lets it call |
|---|---|---|---|
| Jobs | jobs | List jobs, Get job, Get job history | Create job, Update job, Change job status, Assign worker, Unassign worker, Add job note |
| Raw data | raw | List tables, Read table, Export table | Nothing in this area |
| Click IDs and conversions | conv | Get job conversion, Get click id report, Export click id report | Nothing in this area |
These endpoints need no particular area, so any key can call them: Whoami.
Companies
A key reaches only the companies you choose when you make it. Asking for any other company answers `out_of_scope`, and a record in another company answers `not_found`, as if it did not exist. The first call to make is Whoami: it lists the companies the key reaches, with their ids and time zones. How one login holds many client businesses is explained on multiple companies.
Hide personal details
A key sees customers' names, phones and street addresses unless you hide them. Turn on "hide personal details", under Advanced when you make the key or approve an AI app, for a key that reports to a team, or for an AI app that does not need to know who the customers are. Details about a person, such as a name or a phone number, are then kept out of what the key can see. Whoami shows the setting back to your code as hide_personal_details, so a program can tell.
Use the key
Send the key on every call in the Authorization header:
Authorization: Bearer hh_live_...A call without it answers `missing_key`. A key we did not issue, or one that was revoked, answers `unknown_key`.
Shown once, rotated, revoked
- Shown once. The app shows the key at the moment you make it and never again. Store it where only the program that needs it can read it.
- Rotate. If a key is lost or might have leaked, rotate it in the app. You get a new secret, and your code takes the new one.
- Revoke. Revoke a key to stop it for good. Every call made with it afterwards answers
unknown_key.
Each key has its own allowance of calls a minute. The numbers are on errors and rate limits. For the rest of how calls work, read the model. To let an AI app in without handing over a key, see the MCP server.