# AI Gateway Authentication Policy

:::note{title="AI Gateway Policy"}

This policy is for use with the [AI Gateway](/docs/ai-gateway/introduction). See
the AI Gateway documentation to learn how to configure and govern AI models
with Zuplo.

:::

The AI Gateway Authentication policy protects an AI Gateway with application API
keys. It identifies the calling application on `request.user` (`sub` is the
application name, `data` its metadata) and puts the application's AI Gateway
configuration into effect for the policies later in the request pipeline.

Add it to an application's `inboundPolicyChain` to require a key for that app
only, or place it on the route before the configuration executor to require a
key for every application on the route. Clients can send keys with the standard
`Authorization: Bearer` header or with a custom header and scheme.
Authentication results can be cached briefly to reduce request latency.

## Configuration

The configuration shows how to configure the policy in the 'policies.json' document.

```json title="config/policies.json"
{
  "name": "my-ai-gateway-auth-v2-inbound-policy",
  "policyType": "ai-gateway-auth-v2-inbound",
  "handler": {
    "export": "AIGatewayAuthV2InboundPolicy",
    "module": "$import(@zuplo/runtime)",
    "options": {
      "cacheTtlSeconds": 10
    }
  }
}
```

### Policy Configuration

- `name` <code className="text-green-600">&lt;string&gt;</code> - The name of your policy instance. This is used as a reference in your routes.
- `policyType` <code className="text-green-600">&lt;string&gt;</code> - The identifier of the policy. This is used by the Zuplo UI. Value should be `ai-gateway-auth-v2-inbound`.
- `handler.export` <code className="text-green-600">&lt;string&gt;</code> - The name of the exported type. Value should be `AIGatewayAuthV2InboundPolicy`.
- `handler.module` <code className="text-green-600">&lt;string&gt;</code> - The module containing the policy. Value should be `$import(@zuplo/runtime)`.
- `handler.options` <code className="text-green-600">&lt;object&gt;</code> - The options for this policy. [See Policy Options](#policy-options) below.

### Policy Options

The options for this policy are specified below. All properties are optional unless specifically marked as required.

- `cacheTtlSeconds` <code className="text-green-600">&lt;number&gt;</code> - The time to cache authentication results for a particular key. Higher values will decrease latency. Cached results will be valid until the cache expires even in the event the key is deleted, etc. Defaults to `10`.
- `authHeader` <code className="text-green-600">&lt;string&gt;</code> - The name of the header with the key. Defaults to `"Authorization"`.
- `authScheme` <code className="text-green-600">&lt;string&gt;</code> - The scheme used on the header. Defaults to `"Bearer"`.

## Using the Policy

# AI Gateway Authentication

The AI Gateway Authentication policy authenticates requests with an AI Gateway
application API key. After a key is accepted, the calling application is
identified on `request.user` — `sub` is the application name and `data` its
metadata, both readable from custom policies — and the application's AI Gateway
configuration (its selected policy chain, model access, and limits) takes effect
for the request through the AI Gateway policies later in the route.

Use this policy when an application (or every application on a route) must
present an AI Gateway application API key.

A missing or invalid key returns `401 Unauthorized`. A valid key that belongs to
a different application than the route's `app_id` returns `403 Forbidden`.

## Prerequisites

Create the AI Gateway applications and their API keys before calling the
gateway. Each client must use a key issued for one of those applications.

## Add the policy

Declare the policy in `config/policies.json`:

```json
{
  "policies": [
    {
      "name": "ai-gateway-auth-v2-inbound",
      "policyType": "ai-gateway-auth-v2",
      "handler": {
        "export": "AIGatewayAuthV2InboundPolicy",
        "module": "$import(@zuplo/runtime)",
        "options": {
          "cacheTtlSeconds": 60
        }
      }
    }
  ]
}
```

Authentication is optional. Choose where to attach it based on how widely keys
should be required:

### Per application (app-level)

Add the policy to an application's `inboundPolicyChain`. Only that application
requires an API key; other applications on the same route can omit it. The route
should run the configuration executor alone so it can load configuration from
the `app_id` path parameter before the app chain runs:

```json
{
  "inboundPolicyChain": [
    {
      "name": "ai-gateway-auth-v2-inbound"
    }
  ]
}
```

### Every application on the route (route-level)

Add the policy on the route **before** the configuration loader (or before the
executor on executor-only routes). That requires an API key for every
application that hits the route:

```json
{
  "x-zuplo-route": {
    "corsPolicy": "none",
    "handler": {
      "export": "aiGatewayHandlerV2",
      "module": "$import(@zuplo/runtime)",
      "options": {}
    },
    "policies": {
      "inbound": [
        "ai-gateway-auth-v2-inbound",
        "ai-gateway-configuration-loader-v2-inbound",
        "ai-gateway-configuration-executor-v2-inbound"
      ]
    }
  }
}
```

When auth runs on the route, it loads the app configuration from the key and the
loader/executor reuse that channel. When auth is omitted from the route (or only
present in some apps' chains), the loader (or the executor alone) loads
configuration from the route's `app_id` path parameter instead.

> **Protect every public gateway.** Without this policy, the gateway resolves
> the application from the URL and accepts the request without an application
> key. Only leave authentication out when another control, such as network
> isolation, restricts access. Team policy templates can include a locked auth
> entry so new applications require keys by default.

## Call the gateway

By default, clients send the application key as a bearer token:

```bash
curl https://gateway.example.com/v1/chat/completions \
  --header "Authorization: Bearer YOUR_APP_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "openai/gpt-5-mini",
    "messages": [{ "role": "user", "content": "Hello" }]
  }'
```

Authentication scheme matching is case-insensitive. A missing key, an invalid
scheme, or a key that is not authorized receives a `401 Unauthorized` response.

## Use a custom header

Set `authHeader` to accept the key from another header. Set `authScheme` to an
empty string when the header contains only the key:

```json
{
  "name": "ai-gateway-auth-v2-inbound",
  "policyType": "ai-gateway-auth-v2",
  "handler": {
    "export": "AIGatewayAuthV2InboundPolicy",
    "module": "$import(@zuplo/runtime)",
    "options": {
      "authHeader": "x-api-key",
      "authScheme": "",
      "cacheTtlSeconds": 60
    }
  }
}
```

Clients can then call the gateway with:

```bash
curl https://gateway.example.com/v1/chat/completions \
  --header "x-api-key: YOUR_APP_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "model": "openai/gpt-5-mini",
    "messages": [{ "role": "user", "content": "Hello" }]
  }'
```

## Choose a cache duration

`cacheTtlSeconds` controls how long an authentication result can be reused. The
minimum value is 10 seconds.

- Use a shorter duration when key changes must take effect quickly.
- Use a longer duration to reduce authentication latency and repeated validation
  work.

A revoked key can continue to work until its cached result expires.

## Options

- `cacheTtlSeconds`: Number of seconds to cache an authentication result.
  Defaults to `10` and must be at least `10`.
- `authHeader`: Header containing the application key. Defaults to
  `Authorization`.
- `authScheme`: Scheme before the key. Defaults to `Bearer`. Use `""` for a
  header containing the key without a scheme.

Read more about [how policies work](/articles/policies)