# API settings

The API settings endpoints let you read and update an organization's API security settings, mirroring the **Security > API settings** page in the Buildkite UI.

These endpoints require a `read_organization_settings` or `write_organization_settings` [access token scope](/docs/apis/managing-api-tokens#token-scopes), and the authenticated user must be a Buildkite organization administrator.

## Get API settings

```bash
curl -H "Authorization: Bearer $TOKEN" \
  -X GET "https://api.buildkite.com/v2/organizations/{org.slug}/api-settings"
```

```json
{
  "url": "https://api.buildkite.com/v2/organizations/acme-inc/api-settings",
  "allowed_ip_addresses": "192.0.2.0/24 198.51.100.0/24",
  "revoke_inactive_tokens_after_days": 90,
  "restrict_user_api_token_creation": false,
  "features": {
    "api_ip_allow_list": true,
    "inactive_api_token_revocation": true
  }
}
```

Required scope: `read_organization_settings`

Success response: `200 OK`

Error responses:



| `403 Forbidden` | The token does not have the `read_organization_settings` scope, or the authenticated user is not an organization administrator. |
| --- | --- |



## Update API settings

Updates one or more API security settings for the organization. Include only the fields you want to change. The response contains the full updated settings.

```bash
curl -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -X PATCH "https://api.buildkite.com/v2/organizations/{org.slug}/api-settings" \
  -d '{
    "allowed_ip_addresses": "192.0.2.0/24 198.51.100.0/24",
    "revoke_inactive_tokens_after_days": 90,
    "restrict_user_api_token_creation": true
  }'
```

```json
{
  "url": "https://api.buildkite.com/v2/organizations/acme-inc/api-settings",
  "allowed_ip_addresses": "192.0.2.0/24 198.51.100.0/24",
  "revoke_inactive_tokens_after_days": 90,
  "restrict_user_api_token_creation": true,
  "features": {
    "api_ip_allow_list": true,
    "inactive_api_token_revocation": true
  }
}
```

Required scope: `write_organization_settings`

Success response: `200 OK`

Error responses:



| `403 Forbidden` | The token does not have the `write_organization_settings` scope, the authenticated user is not an organization administrator, or the organization's plan does not include the requested plan-gated feature. |
| --- | --- |
| `422 Unprocessable Entity` | A field value failed validation—for example, an IP address not in CIDR notation, a revocation period not in the set of allowed values, or a non-boolean value for `restrict_user_api_token_creation`. |



## Request fields



| `allowed_ip_addresses` | A space-separated string of CIDR ranges that are permitted to make API requests for this organization. Pass `null` to remove the allowlist. Requires the API IP allowlist plan feature; returns `403` if the organization is not entitled. |
| --- | --- |
| `revoke_inactive_tokens_after_days` | Automatically revokes API tokens that have been inactive for the specified number of days. Accepted values are `30`, `60`, `90`, `180`, and `365`. Pass `null` to disable automatic revocation. Requires the inactive API token revocation plan feature; returns `403` if the organization is not entitled. |
| `restrict_user_api_token_creation` | When `true`, only organization administrators can create API access tokens. Accepts `true` or `false`. |



## Response fields



| `url` | The canonical API URL for this resource. |
| --- | --- |
| `allowed_ip_addresses` | The current IP allowlist as a space-separated string of CIDR ranges, or `null` if no allowlist is configured. |
| `revoke_inactive_tokens_after_days` | The number of days of inactivity after which API tokens are automatically revoked, or `null` if automatic revocation is not configured. |
| `restrict_user_api_token_creation` | Whether non-administrator users are prevented from creating API access tokens. |
| `features` | A map of plan-gated features for this organization. Each key corresponds to a feature (`api_ip_allow_list`, `inactive_api_token_revocation`) and its value is `true` if the feature is available on the organization's plan, or `false` if it is not. Use this to distinguish between a setting being configured off and the feature not being available on the plan. |



> 🚧 IP allowlist self-lockout
> The IP allowlist takes effect immediately. If you write a CIDR range that does not include your own IP address, your next API request will be rejected. There is no dry-run mode. This matches the behavior of the UI.