List policies

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)

1 min read

post/v2/gateway.listPolicies

Request example

package main

import(
	"context"
	"os"
	unkey "github.com/unkeyed/sdks/api/go/v2"
	"github.com/unkeyed/sdks/api/go/v2/models/components"
	"log"
)

func main() {
    ctx := context.Background()

    s := unkey.New(
        unkey.WithSecurity(os.Getenv("UNKEY_ROOT_KEY")),
    )

    res, err := s.Gateway.ListPolicies(ctx, components.V2GatewayListPoliciesRequestBody{
        Project: "payments",
        App: "payments-api",
        Environment: "production",
    })
    if err != nil {
        log.Fatal(err)
    }
    if res.V2GatewayListPoliciesResponseBody != nil {
        // handle response
    }
}

Response

{
  "meta": {
    "requestId": "req_123"
  },
  "data": [
    {
      "id": "pol_2gJbXhAr4",
      "name": "Block internal paths",
      "enabled": true,
      "match": [
        {
          "path": {
            "path": {
              "prefix": "/internal/"
            }
          }
        }
      ],
      "firewall": {
        "action": "ACTION_DENY"
      }
    }
  ]
}

post/v2/gateway.listPolicies

Authorization

Authorizationstringheaderrequired#

Unkey uses bearer tokens for authentication. Public integrations use root keys, while the dashboard proxy uses short-lived JWTs.
To authenticate, include the token in the Authorization header of each request:

Authorization: Bearer unkey_123

Root keys have specific permissions attached to them, controlling what operations they can perform. Legacy permissions use tuple strings like api.*.create_key; resource permissions use Unkey Resource Names plus actions, like unkey:v1:ws_123:keyspaces/*#create_key.
Security best practices:

Keep root keys secure and never expose them in client-side code
Use different root keys for different environments
Rotate keys periodically, especially after team member departures
Create keys with minimal necessary permissions following least privilege principle
Monitor key usage with audit logs.

Body

application/json

projectstringrequired#

Identifies a resource by either its unique ID or its slug.
Accepts a prefixed ID (such as 'proj_' or 'app_') or a slug.

Length: 3–255Pattern: ^[a-zA-Z0-9_-]+$

appstringrequired#

Identifies a resource by either its unique ID or its slug.
Accepts a prefixed ID (such as 'proj_' or 'app_') or a slug.

Length: 3–255Pattern: ^[a-zA-Z0-9_-]+$

environmentstringrequired#

Identifies a resource by either its unique ID or its slug.
Accepts a prefixed ID (such as 'proj_' or 'app_') or a slug.

Length: 3–255Pattern: ^[a-zA-Z0-9_-]+$

Responses

application/json

Policies retrieved successfully

metaobjectrequired#

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.

Show child attributes

requestIdstringrequired#

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.

dataobject[]required#

The environment's gateway policies in evaluation order.

Items: max 50

Show child attributes

idstringrequired#

Server-generated policy id. Regenerated on every gateway.setPolicies call, so treat it as stable only until the environment's policies are next replaced.

namestringrequired#

Human-readable name shown in the dashboard.

Length: 1–256

enabledbooleanrequired#

Disabled policies are stored but skipped during evaluation.

matchobject[]#

Optional request matchers. The policy applies only to requests matching
all expressions; omitted when the policy applies to every request.

Items: max 10

Show child attributes

pathobject#

Matches on the request path.

Show child attributes

pathobjectrequired#

String matcher. Exactly one of exact, prefix or regex must be set.

Show child attributes

exactstring#

Matches when the input equals this value.

Length: 1–1024

prefixstring#

Matches when the input starts with this value.

Length: 1–1024

regexstring#

Matches when the input satisfies this RE2 regular expression. Invalid
patterns are rejected when the policy is created.

Length: 1–1024

ignoreCaseboolean#

Compare case-insensitively. May accompany any match mode.

methodobject#

Matches when the request method is one of the listed methods.

Show child attributes

methodsenum<string>[]required#

Items: min 1

headerobject#

Matches a named request field (header or query parameter). Exactly one of
present or value must be set.

Show child attributes

namestringrequired#

Length: 1–256

presentenum<boolean>#

Matches when the field is present, regardless of value.

Options:true

valueobject#

String matcher. Exactly one of exact, prefix or regex must be set.

Show child attributes

exactstring#

Matches when the input equals this value.

Length: 1–1024

prefixstring#

Matches when the input starts with this value.

Length: 1–1024

regexstring#

Matches when the input satisfies this RE2 regular expression. Invalid
patterns are rejected when the policy is created.

Length: 1–1024

ignoreCaseboolean#

Compare case-insensitively. May accompany any match mode.

queryParamobject#

Matches a named request field (header or query parameter). Exactly one of
present or value must be set.

Show child attributes

namestringrequired#

Length: 1–256

presentenum<boolean>#

Matches when the field is present, regardless of value.

Options:true

valueobject#

String matcher. Exactly one of exact, prefix or regex must be set.

Show child attributes

exactstring#

Matches when the input equals this value.

Length: 1–1024

prefixstring#

Matches when the input starts with this value.

Length: 1–1024

regexstring#

Matches when the input satisfies this RE2 regular expression. Invalid
patterns are rejected when the policy is created.

Length: 1–1024

ignoreCaseboolean#

Compare case-insensitively. May accompany any match mode.

keyauthobject#

Verifies Unkey API keys on matching requests.

Show child attributes

keyspacesstring[]required#

Keyspaces to verify keys against, referenced by id. All keyspaces must
belong to your workspace.

Items: 1–5

locationsobject[]#

Where to look for the key on incoming requests, tried in order. Defaults
to the Authorization Bearer header when omitted.

Show child attributes

bearerobject#

Extract the key from the Authorization Bearer header.

headerobject#

Extract the key from a custom header.

Show child attributes

namestringrequired#

Length: 1–256

stripPrefixstring#

Optional prefix removed from the header value before verification.

Length: max 256

queryParamobject#

Extract the key from a query parameter.

Show child attributes

namestringrequired#

Length: 1–256

permissionQuerystring#

Optional permission query the verified key must satisfy, e.g.
documents.read AND documents.write.

Length: max 1000

ratelimitsobject[]#

Rate limits applied during key verification.

Items: max 10

Show child attributes

namestringrequired#

Name of a rate limit configured on the key or its identity, or the name
of the inline override defined by limit and duration.

Length: 1–256

limitinteger#

Inline override: maximum number of operations per window. Must be set
together with duration.

Range: >= 1

durationinteger#

Inline override: window duration in milliseconds. Must be set together
with limit.

Range: >= 1

costinteger#

Cost charged against the limit per request. Defaults to 1.

Range: >= 1

creditsinteger#

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.

Range: >= 0

ratelimitobject#

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.

Show child attributes

limitintegerrequired#

Maximum number of requests per window.

Range: >= 1

windowMsintegerrequired#

Window duration in milliseconds.

Range: >= 1

identifierobjectdeprecated#

How requests are grouped for rate limiting. Exactly one of remoteIp,
header, authenticatedSubject, path or principalField must be set.

Show child attributes

remoteIpobject#

Rate limit by the client's IP address.

headerobject#

Rate limit by the value of a request header.

Show child attributes

namestringrequired#

Length: 1–256

authenticatedSubjectobject#

Rate limit by the authenticated subject (e.g. the verified key).

pathobject#

Rate limit by the request path.

principalFieldobject#

Rate limit by a field extracted from the authenticated principal.

Show child attributes

pathstringrequired#

Length: 1–512

identifiersobject[]#

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.

Items: 1–5

Show child attributes

remoteIpobject#

Rate limit by the client's IP address.

headerobject#

Rate limit by the value of a request header.

Show child attributes

namestringrequired#

Length: 1–256

authenticatedSubjectobject#

Rate limit by the authenticated subject (e.g. the verified key).

pathobject#

Rate limit by the request path.

principalFieldobject#

Rate limit by a field extracted from the authenticated principal.

Show child attributes

pathstringrequired#

Length: 1–512

firewallobject#

Blocks matching requests.

Show child attributes

actionenum<string>required#

What to do with matching requests.

Options:ACTION_DENY

openapiobject#

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.

loggingobject#

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.

Show child attributes

requestHeadersboolean#

Capture request headers, the user agent, and the client IP. The user
agent and client IP are included because they identify the client.

Default: false

responseHeadersboolean#

Capture response headers.

Default: false

requestBodyboolean#

Capture the request body, up to the capture limit.

Default: false

responseBodyboolean#

Capture the response body, up to the capture limit.

Default: false

queryboolean#

Capture the query string and query parameters. Query data is a
separate opt-in because URLs can contain secrets, for example
?api_key=....

Default: false

metaobjectrequired#

Show child attributes

requestIdstringrequired#

errorobjectrequired#

Base error structure following Problem Details for HTTP APIs (RFC 7807). This provides a standardized way to carry machine-readable details of errors in HTTP response content.

Show child attributes

detailstringrequired#

A human-readable explanation specific to this occurrence of the problem. This provides detailed information about what went wrong and potential remediation steps. The message is intended to be helpful for developers troubleshooting the issue.

statusintegerrequired#

HTTP status code that corresponds to this error. This will match the status code in the HTTP response. Common codes include 400 (Bad Request), 401 (Unauthorized), 403 (Forbidden), 404 (Not Found), 409 (Conflict), and 500 (Internal Server Error).

titlestringrequired#

A short, human-readable summary of the problem type. This remains constant from occurrence to occurrence of the same problem and should be used for programmatic handling.

typestringrequired#

A URI reference that identifies the problem type. This provides a stable identifier for the error that can be used for documentation lookups and programmatic error handling. When followed, this URI should provide human-readable documentation for the problem type.

errorsobject[]required#

List of individual validation errors that occurred in the request. Each error provides specific details about what failed validation, where the error occurred in the request, and suggestions for fixing it. This granular information helps developers quickly identify and resolve multiple issues in a single request without having to make repeated API calls.

Show child attributes

locationstringrequired#

JSON path indicating exactly where in the request the error occurred. This helps pinpoint the problematic field or parameter. Examples include:

'body.name' (field in request body)
'body.items[3].tags' (nested array element)
'path.apiId' (path parameter)
'query.limit' (query parameter)
Use this location to identify exactly which part of your request needs correction.

messagestringrequired#

Detailed error message explaining what validation rule was violated. This provides specific information about why the field or parameter was rejected, such as format errors, invalid values, or constraint violations.

fixstring#

A human-readable suggestion describing how to fix the error. This provides practical guidance on what changes would satisfy the validation requirements. Not all validation errors include fix suggestions, but when present, they offer specific remediation advice.

Update environment settings Set policies