Organisations
Set an organisation's key policy
Key expiry (30, 90 or 180 days, or never), whether agents sign in through the browser only, and up to 20 CIDR ranges calls with the organisation's keys must come from.
PUT
/orgs/{org}/policies/keysTL;DR
| Question | Answer |
|---|---|
| What does it do? | Set an organisation's key policy. |
| What does it take? | A JSON body of type KeyPolicyBody. |
| What does it return? | Status 200 with a body of type KeyPolicyResult. |
| What can go wrong? | 400 the body is not valid, or an entry cannot be used (orgs.policy_invalid); 401 not signed in; 403 a member or a reader (orgs.forbidden), a plan without the policies (plan.policies_not_included), or the request came from an origin that may not make changes; 404 no such organisation, or the caller is not a member of it; 429 too many requests; 503 organisations are not set up on this server. Every failure uses the one error envelope. |
What it does
Key expiry (30, 90 or 180 days, or never), whether agents sign in through the browser only, and up to 20 CIDR ranges calls with the organisation's keys must come from. Live keys are given the new expiry; dryRun answers how many. Enterprise; going back to the defaults works on any plan.
Path parameters
| Field | Type | Required | Description |
|---|---|---|---|
org | string | yes | The organisation's id or its slug. |
Request body
The body has the type KeyPolicyBody.
| Field | Type | Required | Description |
|---|---|---|---|
expiryDays | 30 | 90 | 180 | null | yes | "Keys expire after": 30, 90 or 180 days from when a key is made, or null for never. |
browserOnly | boolean | yes | |
networks | string[] | yes | CIDR ranges (203.0.113.0/24, 2001:db8::/32) or single addresses. Each is checked and stored in its canonical spelling. |
dryRun | boolean | no | Answer how many keys would be given a new expiry date, and change nothing. |
revokePersonalKeys | boolean | no | When this change turns browserOnly on: also revoke the personal API keys of the members and readers it holds, and email each of them. Off unless sent. |
Responses
| Status | Meaning | Body |
|---|---|---|
| 200 | The policy as stored, and how many keys changed. | KeyPolicyResult |
| 400 | The body is not valid, or an entry cannot be used (orgs.policy_invalid). | ErrorResponse |
| 401 | Not signed in. | ErrorResponse |
| 403 | A member or a reader (orgs.forbidden), a plan without the policies (plan.policies_not_included), or the request came from an origin that may not make changes. | ErrorResponse |
| 404 | No such organisation, or the caller is not a member of it. | ErrorResponse |
| 429 | Too many requests. | ErrorResponse |
| 503 | Organisations are not set up on this server. | ErrorResponse |
Response body
A 200 answer has the type KeyPolicyResult.
| Field | Type | Required | Description |
|---|---|---|---|
expiryDays | 30 | 90 | 180 | null | yes | "Keys expire after": 30, 90 or 180 days from when a key is made, or null for never. |
browserOnly | boolean | yes | "Agents sign in through the browser only": members and readers on a verified domain make no personal API key, and only the owner and admins make the organisation's keys, for CI. |
networks | string[] | yes | "Keys only from these networks": CIDR ranges, IPv4 or IPv6, in their canonical spelling. Empty is any network. |
keysChanged | integer | yes | The live keys whose expiry date the change set, brought forward or cleared (or with dryRun, would). |
personalKeys | object | yes | When the change turns browserOnly on: the members and readers on a verified domain who hold personal API keys, and how many keys. Otherwise zero. |
personalKeys.members | integer | yes | |
personalKeys.keys | integer | yes | |
personalKeysRevoked | integer | yes | The personal keys the change revoked, with revokePersonalKeys. |
dryRun | boolean | yes |
See also
| Doc | Why |
|---|---|
| API reference | Every endpoint, and the error envelope |
| Schemas | Every request and response type |
| Tool reference | The operations as callable tools |