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, and the authenticated user must be a Buildkite organization administrator.

Get API settings

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

{
  "url": "https://api.buildkite.com/v2/organizations/acme-inc/api-settings",
  "allowed_ip_addresses": "192.0.2.0/24 198.51.100.0/24",
  "allowed_ip_entries": [
    { "ip_address": "192.0.2.0/24", "description": "Office" },
    { "ip_address": "198.51.100.0/24", "description": "" }
  ],
  "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.

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
  }'

{
  "url": "https://api.buildkite.com/v2/organizations/acme-inc/api-settings",
  "allowed_ip_addresses": "192.0.2.0/24 198.51.100.0/24",
  "allowed_ip_entries": [
    { "ip_address": "192.0.2.0/24", "description": "Office" },
    { "ip_address": "198.51.100.0/24", "description": "" }
  ],
  "revoke_inactive_tokens_after_days": 90,
  "restrict_user_api_token_creation": true,
  "features": {
    "api_ip_allow_list": true,
    "inactive_api_token_revocation": true
  }
}

To add a description to each allowed IP address, pass allowed_ip_entries instead of allowed_ip_addresses:

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_entries": [
      { "ip_address": "192.0.2.0/24", "description": "Office" },
      { "ip_address": "198.51.100.0/24" }
    ]
  }'

allowed_ip_addresses and allowed_ip_entries are two representations of the same allowlist. Pass only one of them in a request. Passing both, even if they describe the same list, returns a 422 Unprocessable Entity error.

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 invalid IP address or CIDR range, a revocation period not in the set of allowed values, a non-boolean value for `restrict_user_api_token_creation`, an `allowed_ip_entries` description over 255 characters, or both `allowed_ip_addresses` and `allowed_ip_entries` supplied in the same request.

Request fields

`allowed_ip_addresses`	A space-separated string of IP addresses or CIDR ranges that are permitted to make API requests for this organization. Pass `null` to remove the allowlist. Cannot be supplied together with `allowed_ip_entries`. Requires the API IP allowlist plan feature; returns `403` if the organization is not entitled.
`allowed_ip_entries`	An array of objects that replaces the whole IP allowlist, letting you attach a description to each IP address or CIDR range. Each object has an `ip_address` (required, a single IP address or CIDR range) and a `description` (optional, up to 255 characters, defaults to an empty string when omitted). Pass an empty array to remove the allowlist. Cannot be supplied together with `allowed_ip_addresses`. 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 IP addresses or CIDR ranges, or `null` if no allowlist is configured.
`allowed_ip_entries`	The current IP allowlist as an array of objects, each with an `ip_address` and a `description`. The array is empty if no allowlist is configured. Updates using `allowed_ip_addresses` preserve descriptions for retained addresses with identical spelling. Newly added addresses have an empty string `description`.
`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.