Policies

A policy is a rule that the gateway evaluates on incoming requests. Each policy combines a condition (which requests to match) with an action (what to do). Policies are the building blocks for all of the gateway's request processing, including authentication, rate limiting, and access control.

Policy structure#

Every policy has four components:

You can disable a policy by setting enabled to false. This is useful during incidents when you need to bypass a misbehaving policy without deleting its configuration or triggering a redeploy.

Evaluation order#

The gateway evaluates policies in the order they appear in the configuration:

1. Skip the policy if enabled is false.
2. Evaluate all match conditions. Skip the policy if any condition doesn't match the request.
3. Execute the policy action. If the action rejects the request, return an error response immediately.
4. Move to the next policy.

If all matching policies pass, the gateway forwards the request to your app.

Order matters. Place authentication policies before policies that depend on an authenticated identity (for example, rate limiting by authenticated subject).

Match expressions#

Match expressions control which requests a policy applies to. You can add match conditions when creating or editing a policy in your project's policy settings in the dashboard. A policy can have multiple match conditions, and all conditions must match for the policy to run (AND logic). An empty match list applies the policy to all requests.

Available match types#

All string matching supports three modes:

• Exact: The value must match exactly (for example, /healthz)
• Prefix: The value must start with the specified string (for example, /api/v1)
• Regex: The value must match an RE2 regular expression (for example, ^/users/[0-9]+$)

Each mode supports optional case-insensitive matching.

Combine conditions#

To create AND conditions, add multiple match expressions to a single policy. All expressions must match for the policy to run.

To create OR conditions, create separate policies with the same action but different match expressions.

Policy types#

Error response format#

When a policy rejects a request, the gateway returns a structured JSON error following the RFC 7807 Problem Details format:

{  "meta": { "requestId": "req_abc123" },  "error": {    "title": "Unauthorized",    "detail": "API key is invalid or expired",    "status": 401,    "type": "https://unkey.com/docs/errors/frontline/client/invalid_key"  }}

The type URI is stable per error kind and suitable for programmatic handling. Each policy type maps to a standard HTTP status code: