---
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.
      - `credits` integer — Usage credits a matching request deducts from the verified key. Defaults to 1. Set to 0 to verify the key without spending credits, or to a higher value to charge more per request. Keys with unlimited usage are unaffected.
    - `ratelimit` RatelimitPolicy — Rate limits matching requests. Set `identifiers` with 1 to 5 sources. The deprecated `identifier` field is accepted in place of a one-entry `identifiers` list; set exactly one of the two.
      - `limit` integer, required — Maximum number of requests per window.
      - `windowMs` integer, required — Window duration in milliseconds.
      - `identifier` RatelimitIdentifier — 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
      - `identifiers` RatelimitIdentifier[] — Ordered list of sources that form a compound rate limit key. The gateway resolves each source for each request. Each unique combination of resolved values has its own counter. All counters use the same limit and window. Example: `[authenticatedSubject, path]` limits each subject separately on each path.
        - `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.
    - `logging` LoggingPolicy — Adds request data to the log entries of matching requests. The gateway always records a basic log entry for every request: method, host, path, status, and latency. Each capture setting is a separate opt-in: request headers, response headers, request body, response body, and query data. The policy's `match` expressions select the requests. A policy without `match` expressions matches every request. If more than one enabled logging policy matches a request, the gateway combines their settings. The gateway always redacts the `Authorization` header and configured key locations before it stores headers or query data.
      - `requestHeaders` boolean — Capture request headers, the user agent, and the client IP. The user agent and client IP are included because they identify the client.
      - `responseHeaders` boolean — Capture response headers.
      - `requestBody` boolean — Capture the request body, up to the capture limit.
      - `responseBody` boolean — Capture the response body, up to the capture limit.
      - `query` boolean — Capture the query string and query parameters. Query data is a separate opt-in because URLs can contain secrets, for example `?api_key=...`.

## 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/revisions/68e1a2c609c0/schema)