AI Workforce OneHQDocs

API keys

The keys of your organization. Read only; create, roll and revoke keys in HQ.

List API keys

GET/v1/api_keys
Permission api_keys:read

Every key of the organization, newest first. Metadata only, never a secret.

Query parameters
limitinteger

How many objects to return, 1 to 100. Default 20.

starting_afterstring

Return objects older than this id (the next page).

ending_beforestring

Return objects newer than this id (the previous page).

statusstring

Only active or only revoked keys. One of active, revoked.

Headers
HQ-Versionstring (date)

A dated API version. Defaults to the version the key was created with.

HQ-Accountstring

Agency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with 400 invalid_request on any other credential. A slug that is not one of your agency's current clients is 404 not_found. An agency key is limited to 600 requests a minute per key on EACH API server (the cap is per replica), plus its own budget per client (limit_scope: agency_client), separate from the client's own keys.

Returns a list of ApiKey objects.

Responses
200

A page of keys.

Other

An RFC 9457 problem.

Revoke the calling key

DELETE/v1/api_keys/current
Permission Any valid key

The key making this request revokes itself, at once. Use it the moment a key leaks. Any key may call it; nothing else about keys can be changed through the API.

Headers
HQ-Versionstring (date)

A dated API version. Defaults to the version the key was created with.

HQ-Accountstring

Agency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with 400 invalid_request on any other credential. A slug that is not one of your agency's current clients is 404 not_found. An agency key is limited to 600 requests a minute per key on EACH API server (the cap is per replica), plus its own budget per client (limit_scope: agency_client), separate from the client's own keys.

Responses
204

Revoked. The next request with this key gets 401.

Other

An RFC 9457 problem.

Get an API key

GET/v1/api_keys/{key_id}
Permission api_keys:read
Path parameters
key_idstringrequired

An API key id.

Headers
HQ-Versionstring (date)

A dated API version. Defaults to the version the key was created with.

HQ-Accountstring

Agency keys only: the slug of the client organization this request acts for. Required with an agency key, refused with 400 invalid_request on any other credential. A slug that is not one of your agency's current clients is 404 not_found. An agency key is limited to 600 requests a minute per key on EACH API server (the cap is per replica), plus its own budget per client (limit_scope: agency_client), separate from the client's own keys.

Returns a ApiKey object.

Responses
200

The key.

Other

An RFC 9457 problem.

Objects

ApiKey

An API key. Never carries the key itself.

Attributes
objectstring
idstring
namestring
kindstring

Open-ended; more credential kinds may be added.

prefixstring

The first characters of the key, for recognising it.

last4string
acting_userstring or null
rolestring or null
scopesarray of string
team_scopestring

One of all, selected.

teamsarray of string or null
ip_allowlistarray of string or null

Null when the key has none, and always null unless the caller is an owner or admin key for all teams.

api_versionstring (date)
statusstring

Open-ended: active, expiring_rotation, revoked, expired.

created_atstring (date-time)
created_bystring or null
expires_atstring (date-time)
last_used_atstring or null
last_used_ipstring or null

Always null unless the caller is an owner or admin key for all teams.

revoked_atstring or null
revoked_reasonstring or null
rotated_fromstring or null
rotation_grace_untilstring or null