Address allow lists

Address allow lists restrict access to an API Gateway endpoint to specific IPv4 or IPv6 CIDR network ranges. Unlisted IP addresses are rejected at the edge before reaching your backend workloads.

Configuring IP allowlists

Address ranges are specified in standard CIDR notation (e.g. 203.0.113.0/24 for a network block or 198.51.100.7/32 for a single host).

platformctl

Add CIDR ranges to an endpoint:

platformctl gateway endpoint update support-api \
  --allow-cidr 203.0.113.0/24 --allow-cidr 198.51.100.7/32

Remove all IP restrictions:

platformctl gateway endpoint update support-api --clear-allow-cidr

curl

curl -sS -X PATCH "$CAI_API/v1/projects/$CAI_PROJECT/gateway/endpoints/support-api" \
  -H "Authorization: Bearer $CAI_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"ip_allowlist": ["203.0.113.0/24", "198.51.100.7/32"]}'

Clear all IP restrictions by sending an empty array:

curl -sS -X PATCH "$CAI_API/v1/projects/$CAI_PROJECT/gateway/endpoints/support-api" \
  -H "Authorization: Bearer $CAI_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"ip_allowlist": []}'

Console UI

1. Open your endpoint's Access tab in the Crusoe Console.
2. Under Address Ranges, click Restrict by Address.
3. Enter one CIDR range per line.
4. Click Save.

---

Behavior and Enforcement

• Edge Rejection: Unmatched incoming traffic receives HTTP 403 Forbidden at the Gateway edge. Backend workloads do not receive denied traffic.
• Combined Protection: IP allowlists work alongside authentication modes (jwt, apikey, or none). Callers must satisfy both authentication and IP allowlist criteria.
• Data Service Support: All endpoint target types—including raw protocol connections like Pub/Sub and MemoryStore—support IP allowlists.

---

Common CIDR shapes

Target	Example CIDR Notation
Single IPv4 host	198.51.100.7/32
Office subnet	203.0.113.0/24
Single IPv6 host	2001:db8::1/128
IPv6 network block	2001:db8::/48

---

Verifying IP enforcement

You can verify IP allowlist enforcement by testing requests from permitted vs restricted networks:

# Permitted network request (returns 200 OK)
curl -sS -o /dev/null -w "%{http_code}\n" https://support-api-jxszd4.apps.codyhill.dev/health

# Test with temporary non-matching CIDR (returns 403 Forbidden)
platformctl gateway endpoint update support-api --allow-cidr 192.0.2.0/24
curl -sS -o /dev/null -w "%{http_code}\n" https://support-api-jxszd4.apps.codyhill.dev/health