Set policies

Replace an environment's gateway policies in a single atomic request.
Policies run at the edge before requests reach your app: verify API keys,
rate limit, block requests outright, or validate them against your
OpenAPI spec.

Policies are an ordered list: the gateway evaluates them top to bottom
and the first rejection short-circuits the request.

Each policy sets exactly one of keyauth, ratelimit, firewall or
openapi, plus optional match expressions restricting which requests
it applies to.

Every call is a full replace: the environment's policies become exactly
the request list in the given order, and the server generates a fresh id
for each one. An empty list removes all policies. The operation is
atomic: if any policy is invalid, nothing is written.

Required Permissions

Your root key must have one of the following permissions:

environment.*.set_policies (for any environment)
environment.<environment_id>.set_policies (for a specific environment)

1 min read

post/v2/gateway.setPolicies

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.SetPolicies(ctx, components.V2GatewaySetPoliciesRequestBody{
        Project: "payments",
        App: "payments-api",
        Environment: "production",
        Policies: []components.Policy{
            components.Policy{
                Name: "Block internal paths",
                Enabled: true,
                Match: []components.MatchExpr{
                    components.MatchExpr{
                        Path: &components.PathMatch{
                            Path: components.StringMatch{
                                Prefix: unkey.Pointer("/internal/"),
                            },
                        },
                    },
                },
                Firewall: &components.FirewallPolicy{
                    Action: components.ActionActionDeny,
                },
            },
        },
    })
    if err != nil {
        log.Fatal(err)
    }
    if res.V2GatewaySetPoliciesResponseBody != nil {
        // handle response
    }
}

Response

{
  "meta": {
    "requestId": "req_123"
  },
  "data": {}
}

post/v2/gateway.setPolicies

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_-]+$

policiesobject[]required#

The environment's complete policy list, in evaluation order. Every call
replaces all stored policies with exactly this list; an empty list
removes every policy. The operation is atomic: if any policy is
invalid, nothing is written. An environment can hold at most 50
policies.

Items: max 50

Show child attributes

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; omit to apply 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

Responses

application/json

Successfully set the policies.

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.

dataobjectrequired#

Empty response object by design. A successful response indicates this operation was successfully executed.

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.

List policies Update policy