Endpoints

Manage IP Addresses

The Manage IP Addresses endpoints let you view, add, and replace the CIDR ranges that are permitted to call the nHance API Endpoints for a given API key.

Early Access

IP whitelisting is currently in Early Access and is available for Enterprise clients only. Please contact our support team to enable this feature for your organization.

Endpoint Details

Method	URL	Description
`GET`	`/api/v1/list-ips`	Retrieve all configured CIDR ranges for the API key
`POST`	`/api/v1/manage-ips`	Replace the CIDR allowlist for the API key

Request Parameters

Headers

Header	Type	Required	Description
`X-Client-Id`	string	Yes	Client ID from the API keys page
`X-Client-Secret`	string	Yes	Client secret from the API keys page
`Content-Type`	string	Yes (POST only)	Must be `application/json`

Request Body (POST)

Parameter	Type	Required	Description
`ip_addresses`	array of strings	Yes	List of IPv4 CIDR ranges

Validation Rules

Must be in CIDR notation (e.g., 8.8.8.8/32)
Must be a valid IPv4 address — IPv6 is not supported
CIDR prefix length must be between 0 and 32
Maximum of 5 CIDR ranges per API key
Private, loopback (127.x.x.x) & link-local (169.254.x.x) addresses are rejected

Request Examples

1. List associated CIDR ranges

curl -X GET "https://platform.curiflow.com/api/v1/list-ips" 
  -H "X-Client-Id: your-client-id" 
  -H "X-Client-Secret: your-client-secret"

const response = await fetch('https://platform.curiflow.com/api/v1/list-ips', {
    method: 'GET',
    headers: {
        'X-Client-Id': 'your-client-id',
        'X-Client-Secret': 'your-client-secret'
    }
});

const result = await response.json();

import requests

url = "https://platform.curiflow.com/api/v1/list-ips"
headers = {
    "X-Client-Id": "your-client-id",
    "X-Client-Secret": "your-client-secret"
}

response = requests.get(url, headers=headers)
result = response.json()

2. Replace the CIDR allowlist

The POST endpoint replaces the current allowlist with the provided array. To add a single IP without losing existing ones, retrieve the current list first, append your new entry, and send the full combined array.

curl -X POST "https://platform.curiflow.com/api/v1/manage-ips" 
  -H "Content-Type: application/json" 
  -H "X-Client-Id: your-client-id" 
  -H "X-Client-Secret: your-client-secret" 
  -d '{
    "ip_addresses": ["203.0.113.10/32", "198.51.100.0/24"]
}'

const response = await fetch('https://platform.curiflow.com/api/v1/manage-ips', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        'X-Client-Id': 'your-client-id',
        'X-Client-Secret': 'your-client-secret'
    },
    body: JSON.stringify({
        ip_addresses: ['203.0.113.10/32', '198.51.100.0/24']
    })
});

const result = await response.json();

import requests

url = "https://platform.curiflow.com/api/v1/manage-ips"
headers = {
    "Content-Type": "application/json",
    "X-Client-Id": "your-client-id",
    "X-Client-Secret": "your-client-secret"
}
payload = {
    "ip_addresses": ["203.0.113.10/32", "198.51.100.0/24"]
}

response = requests.post(url, headers=headers, json=payload)
result = response.json()

3. Remove specific CIDR ranges

Because POST replaces the entire allowlist, removing an entry is a read-then-write operation: fetch the current list, remove the unwanted entry, and POST the remaining entries.

The example below removes 198.51.100.0/24 while keeping 203.0.113.10/32.

# Step 1: fetch the current list, then POST only the entries you want to keep
curl -X POST "https://platform.curiflow.com/api/v1/manage-ips" 
  -H "Content-Type: application/json" 
  -H "X-Client-Id: your-client-id" 
  -H "X-Client-Secret: your-client-secret" 
  -d '{
    "ip_addresses": ["203.0.113.10/32"]
}'

// Step 1: GET current list
const getRes = await fetch('https://platform.curiflow.com/api/v1/list-ips', {
    method: 'GET',
    headers: {
        'X-Client-Id': 'your-client-id',
        'X-Client-Secret': 'your-client-secret'
    }
});
const { ip_addresses } = await getRes.json();

// Step 2: Remove the entry you no longer need
const entryToRemove = '198.51.100.0/24';
const updated = ip_addresses.filter((ip) => ip !== entryToRemove);

// Step 3: POST the updated list
const response = await fetch('https://platform.curiflow.com/api/v1/manage-ips', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        'X-Client-Id': 'your-client-id',
        'X-Client-Secret': 'your-client-secret'
    },
    body: JSON.stringify({ ip_addresses: updated })
});

const result = await response.json();

import requests

base_headers = {
    "X-Client-Id": "your-client-id",
    "X-Client-Secret": "your-client-secret"
}

# Step 1: GET current list
get_res = requests.get("https://platform.curiflow.com/api/v1/list-ips", headers=base_headers)
current = get_res.json()["ip_addresses"]

# Step 2: Remove the entry you no longer need
entry_to_remove = "198.51.100.0/24"
updated = [ip for ip in current if ip != entry_to_remove]

# Step 3: POST the updated list
response = requests.post(
    "https://platform.curiflow.com/api/v1/manage-ips",
    headers={**base_headers, "Content-Type": "application/json"},
    json={"ip_addresses": updated}
)
result = response.json()

4. Clear all CIDR ranges

Pass an empty array to POST to remove all IP restrictions from the key.

Removing all the IP restriction means that the request from any IP for that API key will be accepted.

curl -X POST "https://platform.curiflow.com/api/v1/manage-ips" 
  -H "Content-Type: application/json" 
  -H "X-Client-Id: your-client-id" 
  -H "X-Client-Secret: your-client-secret" 
  -d '{"ip_addresses": []}'

const response = await fetch('https://platform.curiflow.com/api/v1/manage-ips', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json',
        'X-Client-Id': 'your-client-id',
        'X-Client-Secret': 'your-client-secret'
    },
    body: JSON.stringify({
        ip_addresses: []
    })
});

const result = await response.json();

import requests

url = "https://platform.curiflow.com/api/v1/manage-ips"
headers = {
    "Content-Type": "application/json",
    "X-Client-Id": "your-client-id",
    "X-Client-Secret": "your-client-secret"
}
payload = {
    "ip_addresses": []
}

response = requests.post(url, headers=headers, json=payload)
result = response.json()

Response Format

GET 200 OK

{
    "client_id": "your-client-id",
    "ip_addresses": [
        "203.0.113.10/32",
        "198.51.100.0/24"
    ]
}

POST 200 OK

{
    "client_id": "your-client-id",
    "message": "IP allowlist updated successfully",
    "ip_addresses": [
        "198.51.100.0/24"
    ]
}

Error response

All errors follow the same envelope:

{
    "error": "Descriptive message about what went wrong"
}

Response Fields

Field	Type	Present on	Description
`client_id`	string	All	The client ID used in the request
`message`	string	POST only	Confirmation of the action performed
`ip_addresses`	array of string	All	Current configured CIDR ranges after the operation
`error`	string	Error responses	Human-readable description of the error

Status and Error Codes

HTTP Code	Message
`200`	Request processed successfully
`400`	`ip_addresses is required` — `ip_addresses` field is missing from the body
`400`	`Invalid CIDR format` — entry is not valid CIDR notation
`400`	`Only IPv4 CIDR ranges are supported` — IPv6 addresses are not accepted
`400`	`Maximum of 5 CIDR ranges allowed per API key`
`400`	`CIDR range already exists` — duplicate entry in a POST request
`400`	`Private IP addresses are not allowed` — loopback, link-local, or RFC-1918 range
`401`	`X-Client-Id and X-Client-Secret are not valid`
`403`	`IP filtering is not enabled for this organization`
`429`	Too many requests — see Rate Limits
`500`	Internal server error
`504`	API gateway timeout

Best Practices

Use the narrowest CIDR possible. A /32 pins enforcement to a single IP. Wider ranges like /16 or /8 increase your exposure surface.

Read before writing. The POST endpoint replaces the entire list. Always GET first, merge your changes locally, and then POST the full updated array. This avoids accidentally removing entries that were set by another process.

Keep the list minimal. Only add ranges that correspond to known egress IPs (e.g., your CI/CD runner, production NAT gateway). Remove stale entries when infrastructure changes.

Test with a non-production key first. Because a bad allowlist can lock out a key, validate your CIDR entries against the validation rules before applying them to a key used in production.

Next Steps

Review the Authentication guide for end-to-end IP filtering behavior.
Manage API key lifecycle from the API Keys page.