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:
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
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
- An agency key needs
HQ-Accounton every request. Without it the answer is400 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:
const hq = new HQ({ apiKey: process.env.HQ_AGENCY_KEY, account: 'bright-dental' });hq = HQ(api_key=os.environ["HQ_AGENCY_KEY"], account="bright-dental")Use one client per SDK instance.
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
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
| 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
- 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.
- Idempotency keys are kept per key per client: the same
Idempotency-Keysent for two different clients is two different requests. See Idempotency.
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.