IP Allowlisting¶

ARX supports per-organization IP allowlisting to restrict API access to known network ranges. When enabled, requests from IP addresses outside the allowlist are rejected before reaching any endpoint handler.

How It Works¶

IP allowlisting is an opt-in security control. When an organization has one or more entries in its IP allowlist, the middleware enforces access restrictions:

• No entries: All IP addresses are allowed (allowlisting is disabled).
• One or more entries: Only requests from IP addresses that match at least one CIDR entry are permitted. All other requests receive a 403 Forbidden response.

This opt-in model means organizations can adopt allowlisting at their own pace without affecting other tenants.

CIDR Format¶

Entries use standard CIDR notation. Both individual addresses and ranges are supported:

ARX validates and normalizes all CIDR inputs. Invalid notation is rejected with 422 Unprocessable Entity.

API Endpoints¶

All IP allowlist endpoints require the admin role.

List Entries¶

GET /v1/settings/ip-allowlist

Returns all allowlist entries for the authenticated user's organization, ordered by creation date (newest first).

Add an Entry¶

POST /v1/settings/ip-allowlist

{
  "cidr": "10.0.0.0/8",
  "description": "Corporate VPN"
}

Returns 201 Created with the new entry. The allowlist cache is cleared immediately so the new entry takes effect on the next request.

Update an Entry¶

PUT /v1/settings/ip-allowlist/{entry_id}

{
  "cidr": "10.0.0.0/16",
  "description": "Updated corporate VPN range"
}

Delete an Entry¶

DELETE /v1/settings/ip-allowlist/{entry_id}

Returns 204 No Content. If this was the last entry, IP allowlisting is effectively disabled for the organization.

Middleware Behavior¶

The IP allowlist middleware evaluates every incoming request:

1. Determines the organization from the authenticated user context.
2. Fetches the allowlist entries (from cache if available).
3. If entries exist, checks the client IP against each CIDR range.
4. If no entry matches, the request is rejected with 403 Forbidden.
5. If no entries exist, the request proceeds normally.

Cache¶

Allowlist entries are cached to minimize database lookups. The cache has a configurable TTL and is invalidated immediately when entries are added, updated, or deleted via the API (the clear_allowlist_cache function is called after every mutation).

Bypassed Paths¶

Certain paths are excluded from IP allowlist enforcement to ensure platform availability:

• /health -- health check endpoint
• /docs -- API documentation
• /redoc -- alternative API documentation
• /openapi.json -- OpenAPI schema

Audit Logging¶

All IP allowlist changes are recorded in the audit log:

Each audit event includes the CIDR value, entry ID, and the user who made the change.

Best Practices¶

1. Start with broad ranges (e.g., your corporate IP range) before narrowing down.
2. Always include your current IP before enabling allowlisting to avoid locking yourself out.
3. Add VPN and CI/CD egress IPs if your team or pipelines use them.
4. Test with a secondary admin account from a known-good IP before removing broad ranges.
5. Use descriptions on every entry to document the purpose of each range.

Troubleshooting¶

Related Documentation¶

• Authentication Overview
• RBAC & Roles
• Rate Limiting