Copy page

Apps

AI Gateway Policy Chains

Every request to an AI Gateway app runs down through the app's policy chain: an ordered list of policies that control model access, budgets, caching, guardrails, and tracing for that app. Different apps on the same gateway can run completely different chains.

The chain works in two layers:

• The gateway declares the menu. config/policies.json in the gateway's repository declares every policy that apps may use —built-in AI Gateway policies and any custom policies you write. Changing the menu is a repository change that takes effect on the next production deploy.
• Each app selects from the menu. An app's chain—which policies run, in what order, with what settings—is edited on the app's Policies tab in the portal. Chain changes apply within about a minute, with no deploy.

No policy is required. An app whose chain is empty still serves requests: each request names its own model, and no model restrictions, budgets, guardrails, or caching apply. Every control is something you add.

A request passes through whatever the app selected before the AI Gateway handler calls the provider:

Code
Request
  → Model Filtering   ─┐
  → Budgets and Costs  ├─ the app's policy chain
  → Custom policy     ─┘
  → AI Gateway handler
  → LLM provider

Editing a chain

The app's Policies tab shows the chain in execution order. Drag entries to reorder them, and click Add Policy to add one from the gateway's menu.

Each declared policy has a single Add button. For a policy with settings, Add opens its settings screen, where you confirm or change the values before the policy joins the chain. For a policy with no settings screen, Add puts it straight into the chain with the options declared in policies.json.

A policy that's already in the chain shows Already added instead of a button—edit it in the chain instead.

Entries seeded by a team policy template may be locked: a lock icon means the template controls whether this app may edit or remove that entry.

How the chain executes

• Entries run in the listed order, after the gateway's route-level policies and before the AI Gateway handler calls the provider.
• A policy can answer the request itself—for example, a semantic cache hit or a guardrail block. Later entries don't run in that case.
• An entry can be disabled to keep its configuration without running it. Disabled entries are still validated, so a disabled entry can't reference a policy that's no longer declared.
• An app with an empty chain runs no app-selected policies; requests go straight to the AI Gateway handler.
• The chain runs on the request path. Policies that need the response—Semantic Cache and the Akamai AI Firewall—register a response hook from their position in the chain, so one entry covers both directions.
• There's no allow-list of policy types. Any policy declared in policies.json is a valid chain entry, including a custom code policy. The only exclusions are the Configuration Executor and its companion Configuration Loader.
• Chain validation is all-or-nothing: if any entry is invalid—for example, it references a policy that isn't declared in the gateway's policies.json—the request fails with an error identifying the entry to fix, and no entries run. The gateway never guesses.

Options and secrets

An entry either inherits the options declared in policies.json or replaces them completely with its own—options are never merged field-by-field. What matters is whether the entry has an options key at all: an entry with empty options replaces the declared options with an empty object, which breaks a policy that has required settings. Omit options entirely to inherit.

Keep credentials in the declaration's options and let entries inherit them, so the gateway's repository—not app configuration—holds them. See Configure credentials.

Recommended order

Code
Model Filtering → Fallback Model → Budgets and Costs → Semantic Cache

• Model Filtering first: it accepts or rejects the request and creates the model selection.
• Fallback Model second: it only enriches an existing model selection and never creates one. A chain with Fallback Model but no Model Filtering does nothing at all—the policy logs a warning and passes the request through unchanged. That's also why a fallback can never bypass the filter.
• Budgets and Costs third: it needs the resolved selection so an exceeded budget can activate the quota fallback.
• Semantic Cache after Budgets and Costs: cache hits still count toward request limits.

Tracing policies work well at the end of the chain, so traces reflect the request the earlier policies produced.

Built-in policies

See the policies overview for every policy an app can run, what each one does, and the identifier it needs in config/policies.json. Any custom policy declared in the repository appears in the Add Policy dialog alongside the built-in ones.

Configuration Executor

ai-gateway-configuration-executor-v2-inbound is the policy that makes the two-layer model work. It loads the app's configuration and then runs the app's stored inbound chain, instantiating only policies already declared in config/policies.json. Every scaffolded gateway declares it and puts it on the AI Gateway route—that route entry is what gives an app's chain somewhere to run.

The scaffolded route also carries a Configuration Loader (ai-gateway-configuration-loader-v2-inbound) ahead of the executor. The executor loads the app's configuration by default, so the loader changes nothing on its own—it's there for when you want to manipulate the loaded configuration programmatically before the chain runs: place your own route policy between the loader and the executor.

Both take a single option, cacheTtlSeconds, which sets how long the gateway caches a loaded app configuration. The default is 10 seconds, 10 is also the minimum, and a lower value throws a configuration error—as does any other option key.

Authentication

The ai-gateway-auth-v2-inbound policy—API Key Authentication in the portal—requires callers to present the app's API key, and it applies per app: add it to an app's chain to require a key for that app alone. A new top-level team's policy template includes it as a locked entry—and sub-teams inherit that template by default—so apps created in the team require keys from the start.

Where the policy applies, clients send the app's API key as a bearer token and the gateway resolves the calling app from the key; for a missing or invalid key the gateway returns a 401 Unauthorized. Its authHeader and authScheme options let the gateway read the key from somewhere other than Authorization: Bearer—x-api-key, for example. The gateway caches key checks for cacheTtlSeconds, which defaults to 10 seconds, so a revoked key can keep working until the cache expires. Each app's key appears on its app page—see Apps.

Next steps

• Custom Policies: write your own policy and add it to a chain
• Policy Templates: seed consistent chains across a team's apps
• Usage Limits: budgets at the gateway, team, and app levels