AI Workforce OneHQDocs

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

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 choseYour agency key
Full access (the default)Works, within the scopes you gave the key
Billing onlyPlan and billing reads only; anything else is 403 permission_denied with reason: agency_access_level
No access403 client_access_disabled
Owners only403 permission_denied with reason: delegation_ceiling: a key is never an owner
Terminal view offNo session history or chat
File reading offNo 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

SituationAnswer
The key is revoked (in HQ, or by itself with DELETE /api_keys/current), expired or unused for 90 days401 invalid_credentials
Your agency account is suspended, on hold by HQ Support, or more than 3 days past due403 agency_suspended
The client turned its provider's access off403 client_access_disabled
The client is no longer one of your clients404 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-Key sent 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.