Copy page

AI Gateway

AI Gateway Authentication Policy

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.

Code
{
  "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 <string> - The name of your policy instance. This is used as a reference in your routes.
• policyType <string> - The identifier of the policy. This is used by the Zuplo UI. Value should be ai-gateway-auth-v2-inbound.
• handler.export <string> - The name of the exported type. Value should be AIGatewayAuthV2InboundPolicy.
• handler.module <string> - The module containing the policy. Value should be $import(@zuplo/runtime).
• handler.options <object> - The options for this policy. See Policy Options below.

Policy Options

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

• cacheTtlSeconds <number> - 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 <string> - The name of the header with the key. Defaults to "Authorization".
• authScheme <string> - 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:

Code
{
  "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:

Code
{
  "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:

Code
{
  "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:

Code
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:

Code
{
  "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:

Code
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