---
title: "List policies"
method: POST
path: "/v2/gateway.listPolicies"
tags: ["gateway"]
---

# List policies

`POST /v2/gateway.listPolicies`

Retrieve an environment's gateway policies in evaluation order: the
gateway evaluates them top to bottom and the first rejection
short-circuits the request.

The full policy list is returned in a single response.

**Required Permissions**

Your root key must have one of the following permissions:
- `environment.*.read_policies` (for any environment)
- `environment.<environment_id>.read_policies` (for a specific environment)

## Request body

- V2GatewayListPoliciesRequestBody
  - `project` string, required — Identifies a resource by either its unique ID or its slug. Accepts a prefixed ID (such as 'proj_' or 'app_') or a slug.
  - `app` string, required — Identifies a resource by either its unique ID or its slug. Accepts a prefixed ID (such as 'proj_' or 'app_') or a slug.
  - `environment` string, required — Identifies a resource by either its unique ID or its slug. Accepts a prefixed ID (such as 'proj_' or 'app_') or a slug.

## Response `200`

Policies retrieved successfully

- V2GatewayListPoliciesResponseBody
  - `meta` Meta, required — Metadata object included in every API response. This provides context about the request and is essential for debugging, audit trails, and support inquiries. The `requestId` is particularly important when troubleshooting issues with the Unkey support team.
    - `requestId` string, required — A unique id for this request. Always include this ID when contacting support about a specific API request. This identifier allows Unkey's support team to trace the exact request through logs and diagnostic systems to provide faster assistance.
  - `data` PolicyResponse[], required — The environment's gateway policies in evaluation order.
    - `id` string, required — Server-generated policy id. Regenerated on every `gateway.setPolicies` call, so treat it as stable only until the environment's policies are next replaced.
    - `name` string, required — Human-readable name shown in the dashboard.
    - `enabled` boolean, required — Disabled policies are stored but skipped during evaluation.
    - `match` MatchExpr[] — Optional request matchers. The policy applies only to requests matching all expressions; omitted when the policy applies to every request.
      - `path` PathMatch — Matches on the request path.
        - `path` StringMatch, required — String matcher. Exactly one of `exact`, `prefix` or `regex` must be set.
          - `exact` string — Matches when the input equals this value.
          - `prefix` string — Matches when the input starts with this value.
          - `regex` string — Matches when the input satisfies this RE2 regular expression. Invalid patterns are rejected when the policy is created.
          - `ignoreCase` boolean — Compare case-insensitively. May accompany any match mode.
      - `method` MethodMatch — Matches when the request method is one of the listed methods.
        - `methods` string[], required
      - `header` FieldMatch — Matches a named request field (header or query parameter). Exactly one of `present` or `value` must be set.
        - `name` string, required
        - `present` true — Matches when the field is present, regardless of value.
        - `value` StringMatch — String matcher. Exactly one of `exact`, `prefix` or `regex` must be set.
          - `exact` string — Matches when the input equals this value.
          - `prefix` string — Matches when the input starts with this value.
          - `regex` string — Matches when the input satisfies this RE2 regular expression. Invalid patterns are rejected when the policy is created.
          - `ignoreCase` boolean — Compare case-insensitively. May accompany any match mode.
      - `queryParam` FieldMatch — Matches a named request field (header or query parameter). Exactly one of `present` or `value` must be set.
        - `name` string, required
        - `present` true — Matches when the field is present, regardless of value.
        - `value` StringMatch — String matcher. Exactly one of `exact`, `prefix` or `regex` must be set.
          - `exact` string — Matches when the input equals this value.
          - `prefix` string — Matches when the input starts with this value.
          - `regex` string — Matches when the input satisfies this RE2 regular expression. Invalid patterns are rejected when the policy is created.
          - `ignoreCase` boolean — Compare case-insensitively. May accompany any match mode.
    - `keyauth` KeyauthPolicy — Verifies Unkey API keys on matching requests.
      - `keyspaces` string[], required — Keyspaces to verify keys against, referenced by id. All keyspaces must belong to your workspace.
      - `locations` KeyLocation[] — Where to look for the key on incoming requests, tried in order. Defaults to the `Authorization Bearer` header when omitted.
        - `bearer` BearerTokenLocation — Extract the key from the `Authorization Bearer` header.
        - `header` HeaderKeyLocation — Extract the key from a custom header.
          - `name` string, required
          - `stripPrefix` string — Optional prefix removed from the header value before verification.
        - `queryParam` QueryParamKeyLocation — Extract the key from a query parameter.
          - `name` string, required
      - `permissionQuery` string — Optional permission query the verified key must satisfy, e.g. `documents.read AND documents.write`.
      - `ratelimits` KeyRatelimit[] — Rate limits applied during key verification.
        - `name` string, required — Name of a rate limit configured on the key or its identity, or the name of the inline override defined by `limit` and `duration`.
        - `limit` integer — Inline override: maximum number of operations per window. Must be set together with `duration`.
        - `duration` integer — Inline override: window duration in milliseconds. Must be set together with `limit`.
        - `cost` integer — Cost charged against the limit per request. Defaults to 1.
    - `ratelimit` RatelimitPolicy — Rate limits matching requests.
      - `limit` integer, required — Maximum number of requests per window.
      - `windowMs` integer, required — Window duration in milliseconds.
      - `identifier` RatelimitIdentifier, required — How requests are grouped for rate limiting. Exactly one of `remoteIp`, `header`, `authenticatedSubject`, `path` or `principalField` must be set.
        - `remoteIp` RemoteIpKey — Rate limit by the client's IP address.
        - `header` HeaderKey — Rate limit by the value of a request header.
          - `name` string, required
        - `authenticatedSubject` AuthenticatedSubjectKey — Rate limit by the authenticated subject (e.g. the verified key).
        - `path` PathKey — Rate limit by the request path.
        - `principalField` PrincipalFieldKey — Rate limit by a field extracted from the authenticated principal.
          - `path` string, required
    - `firewall` FirewallPolicy — Blocks matching requests.
      - `action` 'ACTION_DENY', required — What to do with matching requests.
    - `openapi` OpenapiPolicy — Validates matching requests against the app's uploaded OpenAPI spec. Has no configuration of its own. If no spec has been uploaded for the deployment, the policy is a no-op and requests pass through unvalidated.

## Other responses

- `400` — Bad request
- `401` — Unauthorized
- `403` — Forbidden - Insufficient permissions (requires `environment.*.read_policies`)
- `404` — Not Found - The environment does not exist in your workspace
- `429` — Too Many Requests
- `500` — Internal server error

---

[API](https://skmtc.net/unkeyed/apis/unkey-api.md) · [All operations](https://skmtc.net/unkeyed/apis/unkey-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/unkeyed/unkey-api/versions/fa78aafac89c/schema)