Network Access
Just want to do it in the dashboard? See the guide: Restrict access by IP address.
Network access rules decide which source addresses may reach the API, dashboard and docs. A typical setup keeps the whole instance on the office network and opens one path, a code host’s webhook, to that host’s published addresses only.
In the dashboard: Platform Admin → Security → Firewall. Only platform admins can access it.
Put a network firewall in front first
Section titled “Put a network firewall in front first”These rules run inside the API. A request they refuse has already crossed the internet, reached the proxy and been parsed by the application. Every flaw in front of the filter — the proxy, TLS, the HTTP parser — stays exposed to the whole internet.
Filter at the network edge first: an AWS security group, an Azure network security group, a GCP firewall rule, or the firewall in front of your server. Open only the HTTPS port, and only to the sources that need it: your office or VPN, and your code host’s webhook ranges. If nobody outside your network needs the instance, keep it off the public internet.
Then use these rules as a second layer, for what an edge firewall cannot express: a rule per service and path, lists that refresh from a URL, report mode, and the refused requests on the Traffic tab.
How a request is decided
Section titled “How a request is decided”Two filters run in order. A request must pass both.
- Network rules, before authentication. The rule for the request’s service whose path prefix
is the longest match decides. If no rule matches, the request is allowed. A matching rule allows
the addresses in its lists and CIDRs and refuses everything else with
403 Access denied from this network. - The API key’s own IP allowlist, if the request carries a key that has one. An org admin sets it on Service accounts, and it can only narrow what the rules allow.
The caller’s address is resolved through network.trusted_proxies.
Set it before you write a rule, or every caller has your proxy’s address.
| Example rules | Effect |
|---|---|
api / → office-vpn | The API answers the office only |
api /integrations/github/webhook → github-hooks | …except that path, which answers GitHub’s webhook senders only |
dashboard / → office-vpn | The dashboard pages load from the office only |
/health is never filtered, so load balancers and probes keep working.
An api rule names the path the API serves: /v1/admin, not /admin. Webhooks, callbacks, SCIM
and OAuth stay at the root (see Versioning). Rules written before the /v1
prefix move under it once, at the first start of a version that has it. A rule whose path also
covers a root route, such as /auth, stays and gets a copy under /v1.
A browser denied access to a dashboard or docs page gets a page, not a bare 403. The page says the network is not allowed and shows the address the rules saw, the page, and the time. A Copy details button copies them to the clipboard for an administrator. If the API cannot answer the check, the page says so and retries every 30 seconds.
Report and enforce
Section titled “Report and enforce”A new rule starts in report mode: it counts the requests it would refuse and lets them through. Check the counts on the Rules tab, then switch the rule to enforce.
Address lists
Section titled “Address lists”A list is a named set of entries of one type:
ip— IPs and CIDRs. Rules use these.host— host names and*.suffixpatterns. Egress policies use these (see below).
Its entries come from one source:
| Source | Entries | Refreshed |
|---|---|---|
static | typed in | — |
url | fetched over HTTPS from a public address | on creation, on Refresh now, then every refresh_hours (default 24) |
file | read from a file under network.list_sources_dir | same as url |
A source is plain text, one entry per line with # comments, or JSON. For JSON, selector names
the keys whose strings are collected at any depth: https://api.github.com/meta with
selector: ["hooks"] gives GitHub’s webhook ranges.
Presets. A product can offer ready-made lists for the services it integrates with. Pick one with Add list → From preset.
Default rules. A preset can be marked as a default. At first start, each default becomes
its list and a rule on the preset’s path in report mode: it counts what it would refuse and
blocks nothing. OpenTremor ships one, github-hooks on /integrations/github/webhook. Each default is created
once per deployment: delete it, and it stays deleted. Switch it to enforce once its Traffic looks
right.
File lists are off until the operator sets network.list_sources_dir (env
NETWORK_LIST_SOURCES_DIR) and mounts the directory. A list names a path relative to it; a path
that leaves it is refused. Use a file list for a source on your own network: url lists reach
public addresses only.
Host lists in egress policies
Section titled “Host lists in egress policies”Each egress policy (notifications.egress, and the ones a product adds) takes allowed_lists
next to allowed_hosts. A host is allowed if it is in allowed_hosts or in a named host list.
Naming a list turns the restriction on even while the list is empty: an empty list allows
nothing.
A list that a rule or an egress policy names cannot be deleted. The error names what uses it.
The dashboard and the docs
Section titled “The dashboard and the docs”The API decides for the dashboard and docs too. Their servers ask
GET /network-access/verdict before serving a page:
- the dashboard, through its request proxy, when
NETWORK_ACCESS_VERDICT_URLis set on its container; - the docs, through nginx
auth_request, when the same variable is set on the docs container.
The verdict endpoint answers only a peer listed in network.trusted_proxies and returns 404 to
anyone else. Both servers fail closed: if the API is down, they answer 503. Leave the docs
container without the variable if your docs must stay up during an API outage.
Not locking yourself out
Section titled “Not locking yourself out”- A change that would block your own address from the rules API or the firewall page is refused with 409. The message names the rule.
- New rules start in report mode.
- If you are locked out anyway, set
NETWORK_FILTER_ENABLED=falseon the API and restart. Every rule stops applying, and the firewall page says the operator turned the filter off. The switch is file/env only on purpose: turning the filter off needs access to the deployment.
Traffic and retention
Section titled “Traffic and retention”Every refusal by a rule, in either mode, or by a key’s allowlist is recorded as an event: time, service, path, client address, hop chain, rule or key, request ID. One event per rule or key and address per minute, with a count. The Traffic tab lists them and the most-refused addresses.
Events hold client IP addresses. They are kept for retention.network_events_days (default 7,
up to 90) and deleted with their organization. Change the window on Platform Admin → System
→ Data Lifecycle. Prometheus gets network_access_denied_total{layer,service,mode}.
All endpoints are platform-admin only, except the verdict.
| Endpoint | Purpose |
|---|---|
GET /v1/admin/network-access | Overview: your address and hop chain, rules, lists, key allowlists |
POST /v1/admin/network-access/check | Trace a request: {service, ip, path, api_key_id?} → verdict per layer |
GET/POST /v1/admin/network-access/lists | List, create |
GET /v1/admin/network-access/lists/presets | Registered presets |
GET/PATCH/DELETE /v1/admin/network-access/lists/{list_id} | Read, change, delete (409 while used) |
POST /v1/admin/network-access/lists/{list_id}/refresh | Fetch the source now |
GET/POST /v1/admin/network-access/rules | List (evaluation order), create |
PATCH/DELETE /v1/admin/network-access/rules/{rule_id} | Change, delete (409 on lockout) |
GET /v1/admin/network-access/events | Denial events, newest first; filter by service, layer, ip, ref_id, since |
GET /v1/admin/network-access/events/top-sources | Most-refused addresses |
GET /network-access/verdict | 204 or 403 for a dashboard or docs request; trusted proxies only |
Service and path prefix of a rule, and name, type and source of a list, are fixed once created.