Skip to main content
An OpenAPI validation policy tells the gateway to check each matching request against your ’s OpenAPI spec. Requests that don’t match get a 400, so your code only sees requests the spec allows. The path, query parameters, headers, and body are all checked. OpenAPI 3.0 and 3.1 are supported.

​
Set it up

  1. Serve your OpenAPI document from your app, for example at /openapi.yaml.
  2. Set that path as openapiSpecPath in the ’s runtime settings, in the app’s settings or with environments.updateSettings. It must start with / and be at most 512 characters.
  3. Add the policy: open the app, go to Policies, click Add Policy, and pick OpenAPI Validation. There’s nothing else to configure.
  4. Deploy. When the succeeds, we fetch the spec from it over HTTPS and save it with that deployment.
The policy has no settings. In the API it’s an empty object:
Example
Each deployment checks requests against the spec it was deployed with. A spec change applies when you deploy the version that serves it.

​
What callers see

A request that fails the check gets 400 openapi_validation_failed. The message describes the first problem and, when there is one, the field that caused it. No later policies run, and the request isn’t logged. An Authorization header with the wrong scheme isn’t reported here, because the API key authentication policy gives a clearer error. A missing Authorization header that the spec requires still fails.

​
Troubleshooting

​
Requests aren’t being checked

If the deployment has no spec, the policy does nothing and requests pass through. A deployment has no spec when:
  • openapiSpecPath isn’t set.
  • The path returns a 404 or an empty response.
  • The document is over 10 MiB.
  • Another policy blocked the request for the spec. We fetch it through the gateway like any other request, so keep the spec path out of your API key and firewall policies’ match expressions.
A missing spec never fails the deployment. Fix the cause and redeploy.

​
Every request fails with 422

If the spec is invalid, for example it has a broken schema, every matching request gets 422 invalid_configuration. Fix the spec and redeploy.

​
Hide fields in request logs

Add x-unkey-redact: true to a property in your spec, and its value is hidden in request and response bodies saved by a logging policy. Only that property is hidden, not others with the same name elsewhere in your schemas. Your app still receives the full request.

​
Next steps

Logging policy

Capture bodies so redaction has something to protect.

Gateway errors

The shape of the 400 and 422 responses.
Last modified on September 29, 2026