---
title: "IP Filtering"
description: "Restrict database connections to specific IP addresses or CIDR ranges using per-project IP filtering with optional labels."
canonical: "https://pgbeam.com/docs/ip-allowlist"
last-updated: "2026-09-13T16:16:22.000Z"
---

# IP Filtering

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

URL: https://pgbeam.com/docs/ip-allowlist

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:

## 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.

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

## 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

## Allow a VPC range and a developer IP

## Allow IPv6 ranges

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

## Further reading

Error Codes: SQLSTATE `08004` handling guidance

Troubleshooting: Debug connection rejections

Resilience: Circuit breakers and connection lifecycle