security/ipranges

Use this API endpoint to list, add and delete the trusted IPv4 address ranges from which unrestricted requests can be made using your API key. Requests to this endpoint are authenticated using a Personal Access Token, which you can create on the Personal Access Tokens page. Your account is determined automatically from the token, so you do not need to include your API key in requests to this endpoint.

Tip: Before using this endpoint, review the API key security guidance and then check your current API key security settings. You can always contact support if you need any help or advice.

Authentication

Include your Personal Access Token in the Authorization request header as a bearer token:

Authorization: Bearer your_personal_access_token

The bearer token requires the appropriate scope for each operation:

Operation	Required scope
List IPv4 address ranges	`security-ip:read`
Add an IPv4 address range	`security-ip:write`
Delete an IPv4 address range	`security-ip:write`

Important: Keep your Personal Access Tokens secure. Do not expose them in client-side code or public repositories.

Request URLs

Operation	HTTP method and request URL
List IPv4 address ranges	`https://admin.postcoder.com/api/security/ipranges`
Add an IPv4 address range	`https://admin.postcoder.com/api/security/ipranges`
Delete an IPv4 address range	`https://admin.postcoder.com/api/security/ipranges/{id}`

List IPv4 address ranges

Returns the trusted IPv4 address ranges from which unrestricted requests can be made using your API key.

Example request

curl --fail-with-body --silent --show-error \
	--request GET \
	--header "Accept: application/json" \
	--header "Authorization: Bearer sImV4cCI6MTc5MDk1Nzc4..." \
	"https://admin.postcoder.com/api/security/ipranges"

A successful request returns 200 OK:

{
	"ipranges": [
		{
			"id": "7c8d9e10-4b2a-4f63-91d5-2e7a6b8c3f40",
			"startip": "203.0.113.10",
			"endip": "203.0.113.20",
			"label": "Kubernetes nodes"
		}
	]
}

If your API key has no IPv4 address ranges, ipranges will be an empty array.

Add an IPv4 address range

Adds a trusted IPv4 address range from which unrestricted requests can be made using your API key.

The new range must not overlap an existing range.

To allow a single IPv4 address, use the same address for both startip and endip.

Body parameters

Parameter	Description	Example
`startip`	First IPv4 address in the range	203.0.113.10
`endip`	Last IPv4 address in the range; it must be equal to or greater than the `startip`	203.0.113.20
`label`	An optional description of up to 64 characters	Kubernetes nodes

Example request

curl --fail-with-body --silent --show-error \
	--request POST \
	--header "Accept: application/json" \
	--header "Content-Type: application/json" \
	--header "Authorization: Bearer sImV4cCI6MTc5MDk1Nzc4..." \
	--data '{
		"startip": "203.0.113.10",
		"endip": "203.0.113.20",
		"label": "Kubernetes nodes"
	}' \
	"https://admin.postcoder.com/api/security/ipranges"

A successful request returns 201 Created:

{
	"iprange": {
		"id": "7c8d9e10-4b2a-4f63-91d5-2e7a6b8c3f40",
		"startip": "203.0.113.10",
		"endip": "203.0.113.20",
		"label": "Kubernetes nodes"
	}
}

Delete an IPv4 address range

Deletes an IPv4 address range associated with your API key.

Use the id returned when listing or adding IPv4 address ranges.

Path parameters

Parameter	Description	Example
`id`	The unique ID of the IPv4 address range to delete	7c8d9e10-4b2a-4f63-91d5-2e7a6b8c3f40

Example request

curl --fail-with-body --silent --show-error \
	--request DELETE \
	--header "Accept: application/json" \
	--header "Authorization: Bearer sImV4cCI6MTc5MDk1Nzc4..." \
	"https://admin.postcoder.com/api/security/ipranges/7c8d9e10-4b2a-4f63-91d5-2e7a6b8c3f40"

A successful request returns 204 No Content with an empty response body.

HTTP status codes

Status	Description
`200 OK`	The IPv4 address ranges were returned successfully
`201 Created`	The IPv4 address range was added successfully
`204 No Content`	The IPv4 address range was deleted successfully
`401 Unauthorized`	The bearer token is missing, invalid, expired or revoked
`403 Forbidden`	The bearer token does not have the required scope, or its user no longer has permission to manage the account
`404 Not Found`	The requested IPv4 address range does not exist or cannot be managed through this API
`422 Unprocessable Content`	`startip` or `endip` is invalid, `startip` is greater than `endip`, the IPv4 address range overlaps an existing range, or the `label` is too long
`429 Too Many Requests`	The request rate limit has been exceeded. Wait at least 60 seconds before retrying

Integration advice

IPv6 addresses are not supported
To allow one IPv4 address, provide the same value for startip and endip
Check the HTTP status code before processing the response
Do not retry a 422 Unprocessable Content response without correcting the submitted range

Credit cost

This API endpoint is free to use.