> ## Documentation Index
> Fetch the complete documentation index at: https://unkey-eng-3082-add-portal-config-crud-api-endpoints-v2portal.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# API key authentication

> Configure the gateway to verify Unkey API keys on incoming requests and forward the authenticated identity and metadata to your app.

The API key authentication policy verifies Unkey API keys before requests reach your app. On success, it produces a [Principal](/platform/gateway/principal/overview) 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](/platform/gateway/policies/overview#match-expressions), a custom [key location](#key-location), a [permission query](#permission-query), or a [credit cost](#credit-cost).
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, the key must have enough to cover the request's [credit cost](#credit-cost). Verification deducts that cost (one credit by default). A cost of `0` skips this check.
5. **Rate limits.** All rate limit configurations attached to the key are evaluated. See [rate limiting](/platform/gateway/policies/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](/platform/gateway/principal/overview) and forwards the request with the `X-Unkey-Principal` header. See the [API key source](/platform/gateway/principal/sources/api-key) 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:

| Location    | Description                                                     | Example                        |
| ----------- | --------------------------------------------------------------- | ------------------------------ |
| Bearer      | Extract from the `Authorization: Bearer <key>` header (default) | `Authorization: Bearer sk_123` |
| Header      | Extract from a custom header, with an optional prefix to strip  | `X-API-Key: sk_123`            |
| Query param | Extract from a URL query parameter                              | `?api_key=sk_123`              |

## 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

## Credit cost

By default, each verified request deducts one credit from the key's remaining usage. Set a credit cost on a policy to charge a different amount per route:

* Set the cost to `0` to verify the key without spending any credits. This is useful for read-only endpoints, or when you only want the gateway to confirm the key is valid before proxying to a backend that meters usage itself.
* Set the cost higher than `1` to charge more for expensive endpoints (for example, `3` credits per request).

Keys with unlimited remaining usage are unaffected regardless of the cost. When the cost exceeds the key's remaining credits, the request receives a `429` response.

## Error responses

| Scenario                          | Status | Description                                            |
| --------------------------------- | ------ | ------------------------------------------------------ |
| No credentials provided           | 401    | The request is missing an API key                      |
| Invalid, disabled, or expired key | 401    | The API key failed verification                        |
| Insufficient permissions          | 403    | The key lacks required permissions                     |
| Rate limit exceeded               | 429    | The key's rate limit was exceeded                      |
| Usage limit exceeded              | 429    | The key lacks enough credits to cover the request cost |