# 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:

```bash
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 [#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 [#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 [#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 [#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 [#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 [#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-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:

```bash
curl -X DELETE https://api-hq.aiworkforceone.com/v1/api_keys/current \
  -H "Authorization: Bearer $HQ_API_KEY"
```

## Test and live keys [#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 [#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 [#oauth-apps]

To let **other** software act for a person in HQ (your product, used by people in other
organizations), register an [OAuth app](/docs/api/oauth/) 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.
