IP allowlist API reference

The IP allowlist API contains the following resources:

/cidr-range-lists: Call this resource to create and manage IP allowlists
/cidr-ranges: Call this resource create and manage CIDR ranges and add them to IP allowlists

Use these resources to build IP allowlists that restrict access to HCP Terraform resources based on IP addresses.

Enforcement scopes

Resources in the IP allowlist API support the enforcement-scope attribute, which determines where IP allowlists apply. You can specify one of the following values for the enforcement-scope:

organization: Applies to all resources in the organization except for agent pools. You can set enforcement-scope to organization for only one IP allowlist per organization.
all_agent_pools: Applies to all agent pools in the organization. You can set enforcement-scope to all-agent-pools for multiple IP allowlists per organization.
selected_agent_pools: Applies only to specifically assigned agent pools. This is the default scope. You can set enforcement-scope to selected-agent-pools for multiple IP allowlists per organization.

When you change an IP allowlist's enforcement scope to organization or all_agent_pools, HCP Terraform automatically removes any existing agent pool assignments.

List IP allowlists

GET /organizations/:organization_name/cidr-range-lists

Parameter	Description
`:organization_name`	The name of the organization to list IP allowlists for

Status	Response	Reason
200	Array of JSON API documents (`type: "cidr-range-lists"`)	Success
404	JSON API error object	Organization not found or user not authorized

Query parameters

This endpoint supports pagination with standard URL query parameters. Remember to percent-encode [ as %5B and ] as %5D if your tooling doesn't automatically encode URLs.

Parameter	Description
`page[number]`	Optional. If omitted, the endpoint returns the first page.
`page[size]`	Optional. If omitted, the endpoint returns 10 CIDR range lists per page.
`q`	Optional. A search query string. This query searches CIDR range lists by name. This search is case-insensitive.

Sample request

curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  https://app.terraform.io/api/v2/organizations/my-organization/cidr-range-lists

Sample response

{
  "data": [
    {
      "id": "crl-xKw8dxQPqVQRZmCe",
      "type": "cidr-range-lists",
      "attributes": {
        "name": "Office Network",
        "description": "IP ranges for office locations"
      },
      "relationships": {
        "cidr-ranges": {
          "data": [
            {
              "id": "cidr-6huHpM7asDp7TaiP",
              "type": "cidr-ranges"
            }
          ]
        }
      },
      "links": {
        "self": "/api/v2/cidr-range-lists/crl-xKw8dxQPqVQRZmCe"
      }
    }
  ]
}

Create an IP allowlist

POST /organizations/:organization_name/cidr-range-lists

Parameter	Description
`:organization_name`	The name of the organization to create an IP allowlist in

Status	Response	Reason
201	JSON API document (`type: "cidr-range-lists"`)	Success
404	JSON API error object	Organization not found or user not authorized
422	JSON API error object	Malformed request body, such as missing attributes or unsupported types

Request body

This POST endpoint requires a JSON object with the following properties as a request payload.

Properties without a default value are required.

Key path	Type	Default	Description
`data.type`	string		Must be `"cidr-range-lists"`.
`data.attributes.name`	string		The name of the IP allowlist.
`data.attributes.description`	string	none	A description of the IP allowlist.
`data.attributes.enforcement-scope`	string	`"selected_agent_pools"`	The scope of enforcement for this IP allowlist. Must be one of the following values: `"organization"` `"all_agent_pools"` `"selected_agent_pools"` Only one `"organization"` is allowed per organization.

Sample payload

{
  "data": {
    "type": "cidr-range-lists",
    "attributes": {
      "name": "Office Network",
      "description": "IP ranges for office locations",
      "enforcement-scope": "selected_agent_pools"
    }
  }
}

Sample request

curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request POST \
  --data @payload.json \
  https://app.terraform.io/api/v2/organizations/my-organization/cidr-range-lists

Sample response

{
  "data": {
    "id": "crl-xKw8dxQPqVQRZmCe",
    "type": "cidr-range-lists",
    "attributes": {
      "name": "Office Network",
      "description": "IP ranges for office locations"
    },
    "relationships": {
      "cidr-ranges": {
        "data": []
      }
    },
    "links": {
      "self": "/api/v2/cidr-range-lists/crl-xKw8dxQPqVQRZmCe"
    }
  }
}

Show an IP allowlist

GET /cidr-range-lists/:id

Parameter	Description
`:id`	The ID of the IP allowlist to show

Status	Response	Reason
200	JSON API document (`type: "cidr-range-lists"`)	Success
404	JSON API error object	IP allowlist not found or user not authorized

Sample request

curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  https://app.terraform.io/api/v2/cidr-range-lists/crl-xKw8dxQPqVQRZmCe

Sample response

{
  "data": {
    "id": "crl-xKw8dxQPqVQRZmCe",
    "type": "cidr-range-lists",
    "attributes": {
      "name": "Office Network",
      "description": "IP ranges for office locations",
      "enforcement-scope": "selected_agent_pools"
    },
    "relationships": {
      "cidr-ranges": {
        "data": [
          {
            "id": "cidr-6huHpM7asDp7TaiP",
            "type": "cidr-ranges"
          }
        ]
      }
    },
    "links": {
      "self": "/api/v2/cidr-range-lists/crl-xKw8dxQPqVQRZmCe"
    }
  }
}

Update an IP allowlist

PATCH /cidr-range-lists/:id

Parameter	Description
`:id`	The ID of the IP allowlist to update

Status	Response	Reason
200	JSON API document (`type: "cidr-range-lists"`)	Success
404	JSON API error object	IP allowlist not found or user not authorized
422	JSON API error object	Malformed request body (missing attributes, wrong types, etc.)

Request body

This PATCH endpoint requires a JSON object with the following properties as a request payload.

Key path	Type	Default	Description
`data.type`	string		Must be `"cidr-range-lists"`.
`data.attributes.name`	string	(previous value)	The name of the IP allowlist. If omitted, the existing name is preserved.
`data.attributes.description`	string	(previous value)	A description of the IP allowlist. If omitted, the existing description is preserved.
`data.attributes.enforcement-scope`	string	(previous value)	The scope of enforcement for this IP allowlist. Must be one of the following values: `"organization"` `"all_agent_pools"` `"selected_agent_pools"` Only one `"organization"` is allowed per organization. When changing to `"organization"` or `"all_agent_pools"`, any agent pool assignments are removed.

Sample payload

{
  "data": {
    "type": "cidr-range-lists",
    "attributes": {
      "name": "Updated Office Network",
      "description": "Updated IP ranges for all office locations",
      "enforcement-scope": "all_agent_pools"
    }
  }
}

Sample request

curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request PATCH \
  --data @payload.json \
  https://app.terraform.io/api/v2/cidr-range-lists/crl-xKw8dxQPqVQRZmCe

Sample response

{
  "data": {
    "id": "crl-xKw8dxQPqVQRZmCe",
    "type": "cidr-range-lists",
    "attributes": {
      "name": "Updated Office Network",
      "description": "Updated IP ranges for all office locations",
      "enforcement-scope": "all_agent_pools"
    },
    "relationships": {
      "cidr-ranges": {
        "data": [
          {
            "id": "cidr-6huHpM7asDp7TaiP",
            "type": "cidr-ranges"
          }
        ]
      }
    },
    "links": {
      "self": "/api/v2/cidr-range-lists/crl-xKw8dxQPqVQRZmCe"
    }
  }
}

Delete an IP allowlist

DELETE /cidr-range-lists/:id

Parameter	Description
`:id`	The ID of the IP allowlist to delete

Status	Response	Reason
204	No Content	Success
404	JSON API error object	IP allowlist not found or user not authorized

Sample request

curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request DELETE \
  https://app.terraform.io/api/v2/cidr-range-lists/crl-xKw8dxQPqVQRZmCe

List CIDR ranges for an IP allowlist

GET /cidr-range-lists/:id/relationships/cidr-ranges

Parameter	Description
`:id`	The ID of the IP allowlist to list CIDR ranges for

Status	Response	Reason
200	Array of JSON API documents (`type: "cidr-ranges"`)	Success
404	JSON API error object	IP allowlist not found or user not authorized

Sample request

curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  https://app.terraform.io/api/v2/cidr-range-lists/crl-xKw8dxQPqVQRZmCe/relationships/cidr-ranges

Sample response

{
  "data": [
    {
      "id": "cidr-6huHpM7asDp7TaiP",
      "type": "cidr-ranges",
      "attributes": {
        "cidr-block": "192.168.1.0/24"
      },
      "links": {
        "self": "/api/v2/cidr-ranges/cidr-6huHpM7asDp7TaiP"
      }
    }
  ]
}

Add CIDR ranges to an IP allowlist

POST /cidr-range-lists/:id/relationships/cidr-ranges

Parameter	Description
`:id`	The ID of the IP allowlist to add CIDR ranges to

Status	Response	Reason
201	JSON API document (`type: "cidr-ranges"`)	Success
404	JSON API error object	IP allowlist not found or user not authorized
422	JSON API error object	Malformed request body, such as missing attributes or unsupported types

Request body

This POST endpoint requires a JSON object with the following properties as a request payload.

Properties without a default value are required.

Key path	Type	Default	Description
`data.type`	string		Must be `"cidr-ranges"`.
`data.attributes.cidr-block`	string		The CIDR block (e.g., "192.168.1.0/24" or "10.0.0.0/8").

Sample payload

{
  "data": {
    "type": "cidr-ranges",
    "attributes": {
      "cidr-block": "192.168.1.0/24"
    }
  }
}

Sample request

curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request POST \
  --data @payload.json \
  https://app.terraform.io/api/v2/cidr-range-lists/crl-xKw8dxQPqVQRZmCe/relationships/cidr-ranges

Sample response

{
  "data": {
    "id": "cidr-6huHpM7asDp7TaiP",
    "type": "cidr-ranges",
    "attributes": {
      "cidr-block": "192.168.1.0/24"
    },
    "links": {
      "self": "/api/v2/cidr-ranges/cidr-6huHpM7asDp7TaiP"
    }
  }
}

Show a CIDR range

GET /cidr-ranges/:id

Parameter	Description
`:id`	The ID of the CIDR range to show

Status	Response	Reason
200	JSON API document (`type: "cidr-ranges"`)	Success
404	JSON API error object	CIDR range not found or user not authorized

Sample request

curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  https://app.terraform.io/api/v2/cidr-ranges/cidr-6huHpM7asDp7TaiP

Sample response

{
  "data": {
    "id": "cidr-6huHpM7asDp7TaiP",
    "type": "cidr-ranges",
    "attributes": {
      "cidr-block": "192.168.1.0/24"
    },
    "links": {
      "self": "/api/v2/cidr-ranges/cidr-6huHpM7asDp7TaiP"
    }
  }
}

Update a CIDR range

PATCH /cidr-ranges/:id

Parameter	Description
`:id`	The ID of the CIDR range to update

Status	Response	Reason
200	JSON API document (`type: "cidr-ranges"`)	Success
404	JSON API error object	CIDR range not found or user not authorized
422	JSON API error object	Malformed request body, such as missing attributes or unsupported types

Request body

This PATCH endpoint requires a JSON object with the following properties as a request payload.

Key path	Type	Default	Description
`data.type`	string		Must be `"cidr-ranges"`.
`data.attributes.cidr-block`	string	(previous value)	The CIDR block. If omitted, the existing CIDR block is preserved.

Sample payload

{
  "data": {
    "type": "cidr-ranges",
    "attributes": {
      "cidr-block": "192.168.2.0/24"
    }
  }
}

Sample request

curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request PATCH \
  --data @payload.json \
  https://app.terraform.io/api/v2/cidr-ranges/cidr-6huHpM7asDp7TaiP

Sample response

{
  "data": {
    "id": "cidr-6huHpM7asDp7TaiP",
    "type": "cidr-ranges",
    "attributes": {
      "cidr-block": "192.168.2.0/24"
    },
    "links": {
      "self": "/api/v2/cidr-ranges/cidr-6huHpM7asDp7TaiP"
    }
  }
}

Delete a CIDR range

DELETE /cidr-ranges/:id

Parameter	Description
`:id`	The ID of the CIDR range to delete

Status	Response	Reason
204	No Content	Success
404	JSON API error object	CIDR range not found or user not authorized

Sample request

curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request DELETE \
  https://app.terraform.io/api/v2/cidr-ranges/cidr-6huHpM7asDp7TaiP

Add agent pools to an IP allowlist

POST /cidr-range-lists/:id/relationships/agent-pools

Parameter	Description
`:id`	The ID of the IP allowlist to add agent pools to

This endpoint associates agent pools with an IP allowlist, restricting which IP addresses can access those agent pools.

Status	Response	Reason
204	No Content	Success
404	JSON API error object	IP allowlist not found or user not authorized
422	JSON API error object	Malformed request body, such as missing attributes or unsupported types

Sample request

curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request POST \
  --data @payload.json \
  https://app.terraform.io/api/v2/cidr-range-lists/crl-xKw8dxQPqVQRZmCe/relationships/agent-pools

Remove agent pools from an IP allowlist

DELETE /cidr-range-lists/:id/relationships/agent-pools

Parameter	Description
`:id`	The ID of the IP allowlist to remove agent pools from

This endpoint removes the association between agent pools and an IP allowlist.

Status	Response	Reason
204	No Content	Success
404	JSON API error object	IP allowlist not found or user not authorized

Sample request

curl \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/vnd.api+json" \
  --request DELETE \
  --data @payload.json \
  https://app.terraform.io/api/v2/cidr-range-lists/crl-xKw8dxQPqVQRZmCe/relationships/agent-pools