Copy page

AI Gateway

AI Gateway Configuration Loader Policy

The AI Gateway Configuration Loader loads each application's configuration into the request-scoped channel — reusing the channel from route-level ai-gateway-auth-v2-inbound when present, otherwise fetching by path app_id. It does not run the application's policy chain; place ai-gateway-configuration-executor-v2-inbound after it for that. When this loader is omitted, the executor still loads configuration itself.

Configuration

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

Code
{
  "name": "my-ai-gateway-configuration-loader-v2-inbound-policy",
  "policyType": "ai-gateway-configuration-loader-v2-inbound",
  "handler": {
    "export": "AIGatewayConfigurationLoaderV2InboundPolicy",
    "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-configuration-loader-v2-inbound.
• handler.export <string> - The name of the exported type. Value should be AIGatewayConfigurationLoaderV2InboundPolicy.
• 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 in seconds to cache app configurations loaded by app_id. Defaults to 10 seconds when omitted. Higher values decrease latency; lower values pick up portal changes sooner. Cached results remain valid until the cache expires even if the configuration changes in the portal. When ai-gateway-auth-v2-inbound already loaded the configuration for the request, this cache is not used. Defaults to 10.

Using the Policy

AI Gateway Configuration Loader

The AI Gateway Configuration Loader loads each application's configuration into the request-scoped app-configuration channel. Configuration comes from route-level ai-gateway-auth-v2-inbound when that policy already ran, otherwise from the route's app_id path parameter via Gateway Service.

This policy does not run inboundPolicyChain. Pair it with ai-gateway-configuration-executor-v2-inbound when applications select policies dynamically. If you omit this loader, the executor still loads configuration before running the chain.

Applications can still require API keys later by including ai-gateway-auth-v2-inbound in their own inboundPolicyChain.

Build an AI Gateway from scratch

1. Declare the policies

Add the loader, the executor, and every policy an application may select to config/policies.json:

Code
{
  "policies": [
    {
      "name": "ai-gateway-configuration-loader-v2-inbound",
      "policyType": "ai-gateway-configuration-loader-v2",
      "handler": {
        "export": "AIGatewayConfigurationLoaderV2InboundPolicy",
        "module": "$import(@zuplo/runtime)",
        "options": {
          "cacheTtlSeconds": 60
        }
      }
    },
    {
      "name": "ai-gateway-configuration-executor-v2-inbound",
      "policyType": "ai-gateway-configuration-executor-v2",
      "handler": {
        "export": "AIGatewayConfigurationExecutorV2InboundPolicy",
        "module": "$import(@zuplo/runtime)",
        "options": {
          "cacheTtlSeconds": 60
        }
      }
    }
  ]
}

cacheTtlSeconds sets how long a loaded app configuration is cached by app_id. It defaults to 10 seconds and accepts any value of 2 seconds or more — raise it to cut Gateway Service calls, lower it to pick up portal changes sooner. The AI Gateway project template ships 5 seconds.

Neither the loader nor the executor may appear in an application's inboundPolicyChain. The executor rejects those entries fail-closed.

2. Add the loader and executor to the route

Place the loader before the executor on each AI Gateway route:

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

Authentication is optional and placement controls its scope:

• App-level — add ai-gateway-auth-v2-inbound to an application's inboundPolicyChain. Only that application requires an API key.
• Route-level — add ai-gateway-auth-v2-inbound on the route before the loader. That requires an API key for every application on the route.

Executor-only routes

Routes that list only ai-gateway-configuration-executor-v2-inbound keep working. The executor loads configuration when the channel is empty, then runs the chain. Use the dedicated loader when you want other route policies between load and chain execution, or a clearer separation of concerns.

Configuration checklist

Before deploying:

1. Declare the loader (optional but recommended), the executor, and every selectable policy in config/policies.json.
2. Put the loader before the executor on every AI Gateway route — or put only the executor when you prefer the combined path.
3. Do not add the loader or executor to any application's inboundPolicyChain.

Read more about how policies work