Fresh 2026

Customer blocklist

Merge Gateway's customer blocklist lets org admins deny or pin combinations of customer IDs, providers, and models. Covers the two rule types (block and pin), the 100-rule cap, dashboard + API configuration, the error shape returned to blocked requests, and how rules interact with routing policies.

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:

Rule type	Behavior
Block	Deny the request when the customer and model dimensions both match
Pin	Restrict a customer to a specific allow-list of providers or models. Anything outside the pin is denied.

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:

Dimension	Example
Customer IDs	"customer_abc", "customer_xyz" (the value passed as customer_id on the request)
Providers	"openai", "anthropic", "google" (provider slugs)
Models	"openai/gpt-5.2", "anthropic/claude-sonnet-4-20250514" (full model IDs)

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.

Block rule example

A block rule that denies a specific customer from using any Anthropic model:

{
  "rule_type": "block",
  "customer_ids": ["customer_abc"],
  "providers": ["anthropic"],
  "models": [],
  "reason": "Customer contract, no Anthropic routing"
}

Pin rule example

A pin rule that restricts a customer to two specific OpenAI models:

{
  "rule_type": "pin",
  "customer_ids": ["customer_xyz"],
  "providers": [],
  "models": ["openai/gpt-5.2", "openai/gpt-5-mini"],
  "reason": "Pilot rollout, OpenAI only"
}

---

What blocked requests look like

When a rule denies a request, Gateway returns HTTP 403 with a stable error body:

{
  "error": {
    "message": "Request blocked by organization policy.",
    "type": "blocked_by_policy",
    "code": "customer_model_blocked"
  }
}

The code field tells you which dimension blocked the request:

Code	Meaning
customer_blocked	A block rule denied this customer for all models
customer_model_blocked	A block rule denied this customer for the requested provider or model
provider_blocked	A block rule denied the requested provider for all customers
model_blocked	A block rule denied the requested model for all customers
customer_pinned	A pin rule limited this customer to a different set of providers or models

Handle these the same way you'd handle any other 403. They're stable and safe to match on programmatically.

---

FAQ

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.

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.

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.

Yes. Blocklist rules are evaluated on every request regardless of whether the routing target is a managed or BYOK credential.

Org members with the Manage organization settings permission. Viewing the list requires View organization settings. All create, update, and delete actions are written to the org audit log.

---

Next steps

Restrict routing to vendors in specific countries or regions for data-sovereignty

Every blocklist mutation is recorded. See who changed what, when, and from where.

Blocklist management requires the Manage organization settings permission. Review who holds it.