Gateway policies

Add a policy in the dashboard

1. Open the app and click Policies in the sidebar.
2. Click Add policy, enter a Name, and pick a Type: Key Auth, Rate Limit, Firewall, OpenAPI Validation, or Logging.
3. In the Rule card, click Add condition for each match condition if the policy should only apply to some requests. With no conditions, the If row reads “Every request”. Open the Then row to set the type’s settings.
4. Pick the Environment. The default, All environments, adds the same policy to both production and preview.
5. Click Add policy, then redeploy.

Set policies with the API

• gateway.listPolicies returns the list in the order it runs, with IDs.
• gateway.setPolicies replaces the whole list with the policies array you send, in that order. If any policy is invalid, nothing is saved. An empty array removes every policy. Every policy gets a new ID.
• gateway.updatePolicy changes one policy by policyId. Fields you leave out keep their values, and match: null removes all match expressions. Sending one of keyauth, ratelimit, firewall, openapi, or logging replaces the rule and can change its type.

curl -X POST https://api.unkey.com/v2/gateway.setPolicies \
  -H "Authorization: Bearer $UNKEY_ROOT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "project": "my-project",
    "app": "api",
    "environment": "production",
    "policies": [
      {
        "name": "Require a key",
        "enabled": true,
        "keyauth": { "keyspaces": ["ks_1234abcd"] }
      },
      {
        "name": "100 per minute per key",
        "enabled": true,
        "ratelimit": {
          "limit": 100,
          "windowMs": 60000,
          "identifiers": [{ "authenticatedSubject": {} }]
        }
      }
    ]
  }'

• unkey:v1:<workspace_id>:projects/<project_id>/apps/<app_id>/environments/<environment_id>/gateway/policies/*#write
• unkey:v1:<workspace_id>:projects/<project_id>/apps/<app_id>/environments/<environment_id>/gateway/policies/*#delete

Set policies with the CLI

What’s in a policy

Pick which requests a policy applies to

{
  "name": "Block internal paths",
  "enabled": true,
  "match": [
    { "path": { "path": { "prefix": "/internal/" } } },
    { "method": { "methods": ["POST", "DELETE"] } }
  ],
  "firewall": { "action": "ACTION_DENY" }
}

How paths and methods match

• It ignores case, so /ADMIN matches /admin.
• It ignores a trailing slash, so /admin/ matches /admin, and a prefix of /admin/ matches /admin.
• It removes ; parameters from each segment, so /admin;jsessionid=1 matches /admin.
• It collapses repeated slashes, so /a//admin matches /a/admin.
• It rejects paths with encoded dot segments such as %2e%2e, and double-encoded slashes such as %252F, with ambiguous_path. If an enabled policy matches paths with a regex, it also rejects %2F (an encoded /) and %5C (an encoded \). Frameworks disagree on how to read these, so the gateway can’t match them to policies reliably.

Protect broadly, then narrow

Put policies in the right order

• IP blocks before authentication. Put a firewall policy that blocks by remoteIp above your API key policies, so blocked clients can’t try keys.
• Authentication first. The first API key policy that succeeds decides who the caller is. Later API key policies are skipped.
• Rate limits by caller go after authentication. A rate limit that counts by authenticatedSubject or principalField needs to know the caller, so it needs an enabled API key policy above it. Saving one without that policy fails with a validation error.
• A rejection stops enforcement. After a firewall block, a failed key check, a used-up rate limit, or an OpenAPI error, no later authentication, rate limit, firewall, or validation check runs.

Limits

• 50 policies per environment.
• 10 match expressions per policy.
• 100 entries per remoteIp list.
• 5 keyspaces and 10 key rate limits per API key policy.
• 5 identifiers per rate limit policy.
• Match strings up to 1024 characters, and names up to 256.

Next steps