AI Workforce OneHQDocs

Secrets

Secret names and where they apply. A secret value is never returned.

List an AI team's secrets

GET/v1/teams/{team_id}/secrets
Permission secrets.team:read

Names, scope and teams. A value is never returned.

Path parameters
team_idstringrequired

An AI team id.

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).

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 Secret objects.

Responses
200

A page of secrets.

Other

An RFC 9457 problem.

Create an AI team's secret

POST/v1/teams/{team_id}/secrets
Permission secrets.team:write

The value is write-only: no response carries it, and there is no reveal route on the API.

Path parameters
team_idstringrequired

An AI team id.

Headers
Idempotency-Keystring

Makes a retry safe: the same key and body within 24 hours returns the first response again (Idempotent-Replayed: true); the same key with another body is 422.

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.

Body parameters
namestringrequired
valuestringrequired

Returns a Secret object.

Responses
201

The secret (never its value).

Other

An RFC 9457 problem.

Get an AI team's secret

GET/v1/teams/{team_id}/secrets/{secret_id}
Permission secrets.team:read
Path parameters
team_idstringrequired

An AI team id.

secret_idstringrequired

A secret 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 Secret object.

Responses
200

The secret, without its value.

Other

An RFC 9457 problem.

Delete an AI team's secret

DELETE/v1/teams/{team_id}/secrets/{secret_id}
Permission secrets.team:write
Path parameters
team_idstringrequired

An AI team id.

secret_idstringrequired

A secret id.

Headers
Idempotency-Keystring

Makes a retry safe: the same key and body within 24 hours returns the first response again (Idempotent-Replayed: true); the same key with another body is 422.

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

Done.

Other

An RFC 9457 problem.

List organization secrets

GET/v1/secrets
Permission secrets.org:read

Names, scope and teams. A value is never returned.

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).

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 Secret objects.

Responses
200

A page of secrets.

Other

An RFC 9457 problem.

Create an org secret

POST/v1/secrets
Permission secrets.org:write

Org-wide (scope: org) or shared with chosen teams (scope: selected). The value is write-only: no response carries it, and there is no reveal route on the API. A key restricted to some AI teams creates only selected secrets, for teams inside its restriction (an org-wide one is 403 team_restricted, another team 404).

Headers
Idempotency-Keystring

Makes a retry safe: the same key and body within 24 hours returns the first response again (Idempotent-Replayed: true); the same key with another body is 422.

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.

Body parameters
namestringrequired
valuestringrequired
scopestring

One of org, selected.

teamsarray of string

With scope: selected only.

Returns a Secret object.

Responses
201

The secret (never its value).

Other

An RFC 9457 problem.

Get an organization secret

GET/v1/secrets/{secret_id}
Permission secrets.org:read
Path parameters
secret_idstringrequired

A secret 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 Secret object.

Responses
200

The secret, without its value.

Other

An RFC 9457 problem.

Delete an org secret

DELETE/v1/secrets/{secret_id}
Permission secrets.org:write
Path parameters
secret_idstringrequired

A secret id.

Headers
Idempotency-Keystring

Makes a retry safe: the same key and body within 24 hours returns the first response again (Idempotent-Replayed: true); the same key with another body is 422.

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

Done.

Other

An RFC 9457 problem.

Replace an org secret's value

PUT/v1/secrets/{secret_id}/value
Permission secrets.org:write

The value is write-only: no response carries it, and there is no reveal route on the API.

Path parameters
secret_idstringrequired

A secret id.

Headers
Idempotency-Keystring

Makes a retry safe: the same key and body within 24 hours returns the first response again (Idempotent-Replayed: true); the same key with another body is 422.

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.

Body parameters
valuestringrequired

Returns a Secret object.

Responses
200

The secret (never its value).

Other

An RFC 9457 problem.

Set the teams a selected secret reaches

PUT/v1/secrets/{secret_id}/teams
Permission secrets.org:assign
Path parameters
secret_idstringrequired

A secret id.

Headers
Idempotency-Keystring

Makes a retry safe: the same key and body within 24 hours returns the first response again (Idempotent-Replayed: true); the same key with another body is 422.

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.

Body parameters
teamsarray of stringrequired

Returns a Secret object.

Responses
200

The secret (never its value).

Other

An RFC 9457 problem.

Share a selected secret with one more team

POST/v1/secrets/{secret_id}/teams/{team_id}
Permission secrets.org:assign
Path parameters
secret_idstringrequired

A secret id.

team_idstringrequired

An AI team id.

Headers
Idempotency-Keystring

Makes a retry safe: the same key and body within 24 hours returns the first response again (Idempotent-Replayed: true); the same key with another body is 422.

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

Done.

Other

An RFC 9457 problem.

Stop sharing a selected secret with a team

DELETE/v1/secrets/{secret_id}/teams/{team_id}
Permission secrets.org:assign
Path parameters
secret_idstringrequired

A secret id.

team_idstringrequired

An AI team id.

Headers
Idempotency-Keystring

Makes a retry safe: the same key and body within 24 hours returns the first response again (Idempotent-Replayed: true); the same key with another body is 422.

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

Done.

Other

An RFC 9457 problem.

Replace an AI team's secret value

PUT/v1/teams/{team_id}/secrets/{secret_id}/value
Permission secrets.team:write

The value is write-only: no response carries it, and there is no reveal route on the API.

Path parameters
team_idstringrequired

An AI team id.

secret_idstringrequired

A secret id.

Headers
Idempotency-Keystring

Makes a retry safe: the same key and body within 24 hours returns the first response again (Idempotent-Replayed: true); the same key with another body is 422.

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.

Body parameters
valuestringrequired

Returns a Secret object.

Responses
200

The secret (never its value).

Other

An RFC 9457 problem.

Objects

Secret

A secret's name and where it applies. Deliberately has no value field.

Attributes
objectstring
idstring
namestring
scopestring

One of org, team.

teamsarray of string
created_atstring (date-time)
updated_atstring or null