Customer blocklist
The customer blocklist gives org admins fine-grained control over what each of your customers is allowed to route through. Use it to enforce per-customer model restrictions, deny providers that aren’t approved for a customer’s data, or pin a customer to a specific allow-list of models for a pilot rollout.
How rules work
Blocklist rules are evaluated on every request before routing runs. There are two rule types:
Each org can have up to 100 rules. Block rules always win over pin rules - if the same customer and model combination is both pinned-allowed and explicitly blocked, the request is blocked.
Blocklist rules run on the data-plane hot path. A change in the dashboard syncs to the data plane within seconds and takes effect on the next request.
What you can scope a rule to
Every rule combines three optional dimensions:
Block rule scope requirements: at least one of the three dimensions must be non-empty. A block rule with empty model and provider lists denies every model for the listed customers.
Pin rule scope requirements: customer_ids is required, and at least one of providers or models must be set. A pin rule says “for these customers, only these providers/models are allowed.”
Configuring the blocklist in the dashboard
Go to Configuration → Blocklists in the Merge Gateway dashboard to create, edit, and delete rules. Each rule has an optional human-readable reason field that shows up in the audit log for that rule’s create / update / delete events.
Use the reason field to record the ticket or compliance requirement that drove the rule - it makes audit reviews much faster.
Managing rules via the API
CRUD endpoints on the control-plane API let you manage rules from CI/CD or infrastructure-as-code.
Example payload for a block rule that denies a specific customer from using any Anthropic model:
Example payload for a pin rule that restricts a customer to two specific OpenAI models:
What blocked requests look like
When a rule denies a request, Gateway returns HTTP 403 with a stable error body:
The code field tells you which dimension blocked the request:
Handle these the same way you’d handle any other 403 - they’re stable and safe to match on programmatically.
FAQ
Are blocklist rules evaluated before or after routing policies?
Before. If a rule denies the request, Gateway returns 403 immediately without consulting the routing policy. This means you can’t route around a block by changing strategies.
What happens if a routing policy lists a model that's in a block rule?
The block wins. Gateway filters the policy’s candidate list to remove blocked models before scoring, so the model is never selected. If every candidate is blocked, the request fails with the standard “no eligible vendor” error from the routing policy.
Can I block by IP or end-user location?
No. Blocklist rules target customers (by customer_id), providers, and models - they don’t read the request’s source IP. If you need source-IP filtering, do it at your application layer before calling Gateway. For routing restrictions based on the vendor’s location, see Geo-location routing.
Do block rules apply to BYOK traffic?
Yes. Blocklist rules are evaluated on every request regardless of whether the routing target is a managed or BYOK credential.
Who can manage blocklist rules?
Org members with the manage_org_settings permission. Viewing the list requires view_org_settings. All create / update / delete actions are written to the org audit log.