> This page is for Gateway.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.merge.dev/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.merge.dev/_mcp/server.

# Per-customer restrictions

> Block or pin models and providers for specific customers, or for your whole organization, from the dashboard or the API. Covers rule types, the 403 error codes, and how rules interact with routing policies.

Model restrictions deny, or limit to an allow-list, models and providers for specific customers or for everyone. Use them to enforce a customer contract, keep out an unapproved provider, or pin a pilot customer to a few models.

## Create rules

Manage rules in the dashboard, under **Customers → Model restrictions** ([dashboard](https://gateway.merge.dev/customers/model-restrictions)), or with [`/v1/blocklist-rules`](/merge-gateway/management-api/security-rules/list-blocklist-rules). Changing rules needs Manage organization settings, and every change is recorded in the [audit trail](/merge-gateway/security/audit-trail). An organization can have up to 100 rules, and changes apply to new requests within seconds.

Each rule combines up to three lists, plus an optional **reason** such as a ticket or contract clause:

| List         | Matches                                                                                          |
| ------------ | ------------------------------------------------------------------------------------------------ |
| Customer IDs | The value of the `X-Customer-ID` request header, such as `customer_abc`                          |
| Providers    | The model's provider, the prefix of its ID, such as `anthropic` in `anthropic/claude-sonnet-5-5` |
| Models       | Full model IDs, such as `openai/gpt-5.5`                                                         |

> **Note**
>
> Customer rules match only the `X-Customer-ID` header, not a customer named only through an [Embedded Routing](/merge-gateway/embedded-routing-stack/overview) key or `customer` field.

Providers are model authors, not serving vendors; to limit vendors, use [routing restrictions](/merge-gateway/security/geo-location-routing).

## Rule types

| Type      | Requires                               | Effect                                                                                                                                                                       |
| --------- | -------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Block** | At least one list                      | Denies a request when its customer matches and its model or provider matches. An empty customer list matches everyone, and empty provider and model lists match every model. |
| **Pin**   | Customer IDs, plus providers or models | The listed customers can use only the pinned providers and models. Several pin rules for one customer combine.                                                               |

A block always wins over a pin.

## Blocked requests

A denied request returns HTTP 403:

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

| `code`                   | Rule that matched                                      |
| ------------------------ | ------------------------------------------------------ |
| `customer_blocked`       | A block rule with customers and no providers or models |
| `customer_model_blocked` | A block rule with customers and providers or models    |
| `provider_blocked`       | A block rule with providers only                       |
| `model_blocked`          | A block rule with models and no customers              |
| `customer_pinned`        | A pin rule, when the model is outside the pin          |

## With routing policies

Blocked models are removed from a routing policy's targets, so failover moves to the next permitted model. If every target is blocked, Gateway returns 403 with `type: "permission_error"`, the message "Every model in the routing policy for this request is blocked by your organization's policy.", and the `code` of the rule that blocked the first target.

Rules apply to BYOK traffic too, and `GET /v1/models` leaves out models the caller is blocked from.

## Next steps

#### [Geo-location routing](/merge-gateway/security/geo-location-routing)

Restrict serving vendors and regions

#### [Audit trail](/merge-gateway/security/audit-trail)

See who changed a rule and when

#### [Roles and permissions](/merge-gateway/security/roles-and-permissions)

Review who holds Manage organization settings