Skip to main content
Deploying applications on Unkey is in public beta. To try it, select Projects in the dashboard sidebar and create a project. Deployed resources are free until August 1, 2026. We’re eager for feedback, so let us know what you think on Discord, X, or email support@unkey.com.
The API key authentication policy verifies Unkey API keys before requests reach your app. On success, it produces a Principal containing the key’s identity, metadata, roles, and permissions.

​
Configure API key authentication

To enable API key authentication for your deployment:
  1. Open your project’s policy settings in the dashboard.
  2. Click Add policy.
  3. Select Key Auth as the policy type.
  4. Choose one or more keyspaces to verify against.
  5. Optionally configure match conditions, a custom key location, or a permission query.
  6. Select which environments (production, preview, or both) to enable the policy for.
  7. Save the policy.
Once configured, the gateway verifies every incoming request that matches the policy’s conditions against the selected keyspaces. Requests without a valid API key receive a 401 response and never reach your app.

​
How verification works

The gateway extracts the API key from the Authorization header (as a Bearer token) and verifies it against your configured keyspaces. The following checks run in order:
  1. Existence. The key must belong to one of the configured keyspaces.
  2. Status. The key must not be disabled or revoked.
  3. Expiration. The key must not have passed its expiration timestamp.
  4. Credits. If remaining credits are configured, at least one credit must be available. Verification deducts one credit.
  5. Rate limits. All rate limit configurations attached to the key are evaluated. See rate limiting for details on response headers and behavior.
  6. Permissions. If a permission query is configured, the key must satisfy it.
If all checks pass, the gateway produces a Principal and forwards the request with the X-Unkey-Principal header. See the API key source for the full list of fields your app receives, including roles, permissions, and key metadata.

​
Key location

By default, the gateway extracts the API key from the Authorization header as a Bearer token. You can override this by adding a custom key location when creating or editing a policy:

​
Permission query

You can enforce Unkey RBAC permissions directly in the gateway by setting a permission query on a policy. If the authenticated key lacks the required permissions, the request receives a 403 response before reaching your app. Permission queries support AND and OR operators:
  • api.read AND api.write requires both permissions
  • api.read OR api.write requires either permission

​
Error responses

Last modified on June 24, 2026