Skip to main content

IP allowlisting

Every API key supports an optional list of allowed source IPs. When set, requests from any other IP return HTTP 403 IP address not allowed.

When to use this​

  • The integrating server has a small set of known, stable egress IPs (NAT gateway, dedicated proxy).
  • You want a defence-in-depth layer in addition to the API key.

When not to use this​

  • Serverless platforms with rotating egress IPs (most managed serverless products).
  • Multi-region failover where the egress set is large or changes per deploy.

Leaving the allowlist empty disables the check for that key.

How the client IP is determined​

The client IP is taken from the first entry of X-Forwarded-For if present, otherwise the direct peer address. Behind a CDN or load balancer, ensure your edge is configured to set or pass through X-Forwarded-For correctly.

Setting an allowlist​

Set the allowlist when creating or updating a key from the Settings → API Keys page in the FlowBeacon console. Each entry is an IPv4 or IPv6 address. CIDR ranges are not currently supported.

Avoiding lock-out​

  1. Allowlist before flipping production traffic. Verify the new key works from the target environment with a GET /governance/health followed by an authenticated call.
  2. Keep a break-glass key. Maintain a second key without an IP allowlist scoped to read-only operations, stored in a secure secret manager and audited. Use it to re-enable access if the allowlisted key locks itself out.
  3. Monitor IP address not allowed errors. They usually mean an egress IP changed unannounced. The FlowBeacon console shows recent denials by IP for diagnosis.

Common environments​

EnvironmentLikely egress strategy
AWS EC2 behind a NAT GatewayPin to the NAT Gateway's Elastic IP.
AWS LambdaEgress IPs rotate — do not allowlist.
Cloudflare WorkersEgress IPs are large pool — do not allowlist.
Vercel / Netlify functionsEgress IPs are large pool — do not allowlist.
On-prem / GCP / Azure VMPin to the static egress IP of the VPC.

Next steps​