# Agency keys

One key for your agency, acting for one client at a time with the HQ-Account header. What it can do, what it never can, and how your clients stay in control.



An **agency key** belongs to your agency, not to one client. Each request names the client it acts
for in the `HQ-Account` header:

```bash
curl https://api-hq.aiworkforceone.com/v1/teams \
  -H "Authorization: Bearer $HQ_AGENCY_KEY" \
  -H "HQ-Account: bright-dental"
```

The value is the client's slug, the part of its address in your console. Every response is about
that client only, exactly as if one of your Account managers were working in it.

## Create an agency key [#create-an-agency-key]

In your agency's HQ, open **Settings**, then **Developers**, and create a key with the type
**Agency key**. Agency owners and Account managers can create one. You confirm it is you first, and
the key is shown once: store it in your secret manager.

An agency key:

* acts as your agency's **Account manager** role, never as a person;
* reaches every AI team of the client it acts for (it cannot be narrowed to some teams);
* lasts up to one year, like a service key, and switches off after 90 days unused.

## Which client: HQ-Account [#which-client-hq-account]

* An agency key **needs** `HQ-Account` on every request. Without it the answer is
  `400 invalid_request`.
* Any other key or app token **must not** send it: the answer is `400 invalid_request`.
* A slug that is not one of your agency's current clients is `404 not_found`, the same answer for a
  client of another agency, a direct customer, or a slug that does not exist.

With an SDK, pass the client once:

```ts
const hq = new HQ({ apiKey: process.env.HQ_AGENCY_KEY, account: 'bright-dental' });
```

```python
hq = HQ(api_key=os.environ["HQ_AGENCY_KEY"], account="bright-dental")
```

Use one client per SDK instance.

## What your clients control [#what-your-clients-control]

Your clients decide what their provider may do, in **Settings**, **Provider access**. Your agency
key follows their choice on every request:

| The client chose          | Your agency key                                                                                          |
| ------------------------- | -------------------------------------------------------------------------------------------------------- |
| Full access (the default) | Works, within the scopes you gave the key                                                                |
| Billing only              | Plan and billing reads only; anything else is `403 permission_denied` with `reason: agency_access_level` |
| No access                 | `403 client_access_disabled`                                                                             |
| Owners only               | `403 permission_denied` with `reason: delegation_ceiling`: a key is never an owner                       |
| Terminal view off         | No session history or chat                                                                               |
| File reading off          | No file reads                                                                                            |

A change takes effect on your next request.

## What an agency key never does [#what-an-agency-key-never-does]

Whatever a client allows and whatever scopes the key has, an agency key never:

* reads a secret value or a variable value, or changes a secret or a variable;
* types into a session, starts one, or uses anyone's personal Claude or ChatGPT sign-in;
* creates or changes a schedule, writes or downloads files, or downloads session history;
* invites people, changes who has access to a team, or creates or deletes a team;
* manages the client's API keys, apps, webhooks, roles, security settings, ownership, cancellation
  or payment method.

These answer `403 permission_denied` with `reason: delegation_ceiling`. A key cannot even be created
with these scopes.

## When it stops working [#when-it-stops-working]

| Situation                                                                                               | Answer                                             |
| ------------------------------------------------------------------------------------------------------- | -------------------------------------------------- |
| The key is revoked (in HQ, or by itself with `DELETE /api_keys/current`), expired or unused for 90 days | `401 invalid_credentials`                          |
| Your agency account is suspended, on hold by HQ Support, or more than 3 days past due                   | `403 agency_suspended`                             |
| The client turned its provider's access off                                                             | `403 client_access_disabled`                       |
| The client is no longer one of your clients                                                             | `404 not_found`                                    |
| The client is on hold because of your agency's account (day 14)                                         | Reads work; every change is `403 agency_suspended` |

## Limits and retries [#limits-and-retries]

* **Rate limits** apply per key (600 requests a minute across all your clients, on each API server)
  and per client (a budget for your agency in that client, separate from the client's own). See
  [Rate limits](/docs/api/rate-limits/).
* **Idempotency keys** are kept per key per client: the same `Idempotency-Key` sent for two
  different clients is two different requests. See [Idempotency](/docs/api/idempotency/).

## Audit [#audit]

Every change your key makes is recorded in the client's audit log as "\<Your agency> support",
with the key and the link it used, and a copy is recorded in your agency's own audit log, without
the client's content.
