IP Filtering

Restrict database connections to specific IP addresses or CIDR ranges using per-project IP filtering with optional labels.

IP filtering lets you restrict which client IP addresses can connect to a project through PgBeam. When enabled, connections from IPs outside the allowlist are rejected before authentication — they never reach the upstream database.

How it works

Each project has an optional list of CIDR filtering rules. When the list is non-empty, PgBeam checks every incoming connection's source IP against the rules during the TLS handshake, before any PostgreSQL protocol exchange.

Filter state	Behavior
Empty (default)	All IPs are allowed
One or more CIDR rules	Only matching IPs are allowed; others are rejected

Rejected connections receive a FATAL error and the connection is closed immediately:

FATAL: connection rejected: IP not in allowlist
SQLSTATE: 08004

Configure IP filtering

You can manage IP filtering from the dashboard, API, or CLI. Each entry consists of a CIDR range and an optional label. Use /32 for a single IPv4 address or /128 for a single IPv6 address.

Navigate to your project and go to Settings > Security. Toggle IP filtering on, then add CIDR blocks with optional labels. Changes take effect within seconds across all data plane regions.

curl -X PATCH \
  https://api.pgbeam.com/v1/projects/{projectId} \
  -H "Authorization: Bearer <key>" \
  -H "Content-Type: application/json" \
  -d '{
    "allowed_cidrs": [
      { "cidr": "203.0.113.0/24", "label": "Office" },
      { "cidr": "198.51.100.42/32", "label": "CI/CD" },
      { "cidr": "2001:db8::/32", "label": "IPv6 range" }
    ]
  }'

pgbeam projects update <project-id> \
  --allowed-cidrs "203.0.113.0/24,198.51.100.42/32,2001:db8::/32"

To disable IP filtering, set it to an empty array:

curl -X PATCH \
  https://api.pgbeam.com/v1/projects/{projectId} \
  -H "Authorization: Bearer <key>" \
  -H "Content-Type: application/json" \
  -d '{ "allowed_cidrs": [] }'

Limits

Maximum 50 CIDR entries per project
Both IPv4 and IPv6 CIDR notation are supported
Each entry supports an optional human-readable label (max 100 characters)
A plain IP without prefix length defaults to /32 (IPv4) or /128 (IPv6)
Changes propagate to all data plane regions within seconds via the config streaming channel

Common patterns

Allow a single office IP

{ "allowed_cidrs": [{ "cidr": "203.0.113.42/32", "label": "Office" }] }

Allow a VPC range and a developer IP

{
  "allowed_cidrs": [
    { "cidr": "10.0.0.0/8", "label": "VPC" },
    { "cidr": "198.51.100.1/32", "label": "Dev laptop" }
  ]
}

Allow IPv6 ranges

{
  "allowed_cidrs": [
    { "cidr": "2001:db8::/32", "label": "IPv6 prefix" },
    { "cidr": "fd00::/8", "label": "Private IPv6" }
  ]
}

Make sure to include the IP ranges of all environments that connect through PgBeam — production servers, CI/CD pipelines, developer machines, and any monitoring tools. Forgetting an IP range will block those connections.

Interaction with other features

IP allowlisting is checked before authentication, connection pooling, and all other proxy features. The evaluation order for an incoming connection is:

TLS handshake and SNI-based project lookup
IP allowlist check (if configured)
Authentication (credentials forwarded to upstream)
Connection pooling and query relay

This means:

Blocked IPs never consume a connection slot
Blocked IPs never trigger auth rate limiting
The upstream database never sees traffic from disallowed IPs