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",
  "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",
  "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.