# Set an organisation's key policy

> Page: https://docs.plotwork.dev/api/put-orgs-org-policies-keys. Index of every page: https://docs.plotwork.dev/llms.txt

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/keys`

## TL;DR

| Question | Answer |
|---|---|
| What does it do? | Set an organisation's key policy. |
| What does it take? | A JSON body of type [`KeyPolicyBody`](https://docs.plotwork.dev/api/schemas.md#keypolicybody). |
| What does it return? | Status 200 with a body of type [`KeyPolicyResult`](https://docs.plotwork.dev/api/schemas.md#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`](https://docs.plotwork.dev/api/schemas.md#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`](https://docs.plotwork.dev/api/schemas.md#keypolicyresult) |
| 400 | The body is not valid, or an entry cannot be used (orgs.policy_invalid). | [`ErrorResponse`](https://docs.plotwork.dev/api/schemas.md#errorresponse) |
| 401 | Not signed in. | [`ErrorResponse`](https://docs.plotwork.dev/api/schemas.md#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`](https://docs.plotwork.dev/api/schemas.md#errorresponse) |
| 404 | No such organisation, or the caller is not a member of it. | [`ErrorResponse`](https://docs.plotwork.dev/api/schemas.md#errorresponse) |
| 429 | Too many requests. | [`ErrorResponse`](https://docs.plotwork.dev/api/schemas.md#errorresponse) |
| 503 | Organisations are not set up on this server. | [`ErrorResponse`](https://docs.plotwork.dev/api/schemas.md#errorresponse) |

## Response body

A 200 answer has the type [`KeyPolicyResult`](https://docs.plotwork.dev/api/schemas.md#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](https://docs.plotwork.dev/api/reference.md) | Every endpoint, and the error envelope |
| [Schemas](https://docs.plotwork.dev/api/schemas.md) | Every request and response type |
| [Tool reference](https://docs.plotwork.dev/mcp/tools.md) | The operations as callable tools |