Policies

Policies are configurable rules the gateway evaluates on every request. Combine authentication, rate limiting, IP rules, and more.

Deploying applications on Unkey is in public beta. To try it, select Projects in the dashboard sidebar and create a project. Deployed resources are free until August 1, 2026. We’re eager for feedback, so let us know what you think on Discord, X, or email [e-mail].

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:

Field	Description
name	Human-readable label for identification
enabled	Toggle to disable the policy without removing it
match	Conditions that determine which requests the policy applies to
config	The action to perform (authentication, rate limiting, IP rules, or validation)

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

Type	Matches on	Example use case
Path	URL path	Apply auth to /api/v1 paths only
Method	HTTP method	Rate limit POST requests but not GET
Header	Request header and value	Enforce policies when X-Custom-Header is present
Query parameter	URL query parameter	Match requests with a specific version parameter

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

Type	Status	Description
API key authentication	Available	Verify Unkey API keys and forward identity to your app
Logging	Available	Record full HTTP requests and responses for debugging
JWT authentication	Coming soon	Validate Bearer JWTs using JWKS, OIDC, or PEM public keys
Rate limiting	Available	Enforce rate limits
Firewall	Available	Deny requests based on path, method, header, or query
OpenAPI validation	Available	Validate requests against an OpenAPI 3.0/3.1 specification

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:

Policy type	Rejection status
Authentication (missing or invalid)	401
Authentication (insufficient permissions)	403
Rate limiting	429
IP rules	403
OpenAPI validation	400