Authentication
API keys, the difference between your own keys and service keys, scopes, expiry, allowlists, rolling and revoking.
Every request carries an API key in the Authorization header:
curl https://api-hq.aiworkforceone.com/v1/me -H "Authorization: Bearer $HQ_API_KEY"The API reads keys from that header only. It never reads a key from a query string, and it never accepts an HQ sign-in cookie: a browser signed in to HQ cannot call the API by accident.
Two kinds of key
| Your own key | Service key | |
|---|---|---|
| Created in | Profile, API keys | Settings, Developers (owners and admins) |
| Acts as | You | The organization, with a role you pick (Member or Admin) |
| Can do | At most what you can do in HQ, today | At most what its role can do |
| When its creator leaves | Stops working | Keeps working; owners and admins are asked to review it |
| Longest life | 90 days | 1 year |
Use your own key for your scripts and experiments. Use a service key for CI and production systems that must keep working when people change.
When the person who created a service key leaves the organization, the key keeps working: it belongs to the organization. The owners and admins are emailed the list of such keys, and Settings, Developers marks each one Creator left. Revoke the ones you no longer need. To keep one, roll it: the new key is yours.
A service key never acts as a person, so it can never use anyone's personal Claude or ChatGPT sign-in. A Member-role service key reaches no AI team on its own; give it the Admin role to reach every AI team, or narrow it to some teams.
Scopes
A key holds scopes: the HQ permissions it may use, such as teams:read or audit:read. Pick
only what the key needs. When you create a key, scopes above your own access are turned off.
Read only, everything I can see ticks every read scope you hold and nothing that changes
anything (not even waking a Cloud Computer).
Every change a key makes shows in the HQ audit log as made "via API key" with the key's name, or "via" the app's name and "(OAuth)" for an OAuth app. Someone who cannot see the organization's keys or installed apps reads "via an API key" or "via an OAuth app".
On every request the key's scopes are checked against what its person or role can do right now. If someone's access is reduced in HQ, every key they hold is reduced on its next request, with no change to the key.
A request without the needed scope answers 403 permission_denied, naming the missing permission.
Limiting a key
- AI teams. Restrict a key to some AI teams. Anything on another team answers
404, as if it did not exist, and lists leave other teams out: secrets and variables shared with other teams only, the org chart's teams and the usage of other teams. Organization-wide secrets and variables stay visible. The audit log covers every team, so such a key cannot read it (403). Listing API keys, it sees itself and keys limited to its own teams, without their IP details. - IP allowlist. Give a key up to 32 addresses or ranges. A call from anywhere else answers
403 ip_not_allowed.
Expiry and unused keys
Keys always expire: your own keys within 90 days, service keys within a year. A key nobody uses for
90 days switches off on its own. An expired or switched-off key answers 401 invalid_credentials.
If your organization requires two-factor authentication, your own keys work only while you have it
turned on (403 two_factor_required otherwise). Changing your password does not stop your keys: the
email HQ sends lists them, so you can revoke any you do not recognise.
New location notices
The first time a key is used from a network it has never been used from, HQ emails the person it acts as, or, for a service key, the organization's owners and admins. If it was not you or your automation, revoke the key. A key used from very many networks gets one notice saying so, then at most one a day while new networks keep appearing.
Rolling a key
Roll makes a new key with the same name, scopes and limits. You choose how long the old key keeps working (none, 1 hour, 24 hours or 7 days) so your systems can switch over. The new key is shown once, like a new key.
If you revoke the new key, the old one stops at the same moment, even inside its overlap: revoking after a roll is how you respond to a leak.
Revoking a key
Revoking takes effect on the key's next request. You can revoke your own keys in HQ, admins can revoke any key in Settings, Developers, and a key can revoke itself:
curl -X DELETE https://api-hq.aiworkforceone.com/v1/api_keys/current \
-H "Authorization: Bearer $HQ_API_KEY"Test and live keys
Keys start with hq_live_ in production and hq_test_ in the test environment. A key only works in
its own environment.
Keeping keys safe
- Store keys in a secret manager or your CI's secrets, never in code.
- Never ship a key in a browser or mobile app.
- Give each system its own key, with only the scopes it needs, so you can revoke one without the others.
The key appears in HQ only once, when it is created. HQ stores only a keyed hash of it and can never show it again.
OAuth apps
To let other software act for a person in HQ (your product, used by people in other
organizations), register an OAuth app instead of handing out keys. The person
approves it for one organization, it never does more than they can, and it never sends prompts. Its
access token goes in the same Authorization: Bearer header.