AI Gateway

Akamai AI Firewall Policy

AI Gateway Policy

This policy is for use with the AI Gateway. See the AI Gateway documentation to learn how to configure and govern AI models with Zuplo.

The Akamai AI Firewall policy scans AI Gateway prompts and completions with Akamai Firewall for AI. One inbound policy protects both request and response content, including streaming responses, and blocks content that an Akamai rule denies.

For runtime inspection, the policy denies unknown endpoint shapes and handled Akamai detection-call failures by default. If a recognized request or successful response has an unparseable JSON body, the policy skips scanning that body and passes it through. Detection rules and categories are configured in Akamai Control Center.

Configuration

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


Code
{
  "name": "my-akamai-ai-firewall-v2-inbound-policy",
  "policyType": "akamai-ai-firewall-v2-inbound",
  "handler": {
    "export": "AkamaiAIFirewallV2InboundPolicy",
    "module": "$import(@zuplo/runtime)",
    "options": {
      "configurationId": "$env(AKAMAI_AI_FIREWALL_CONFIGURATION_ID)",
      "api-key": "$env(AKAMAI_AI_FIREWALL_API_KEY)"
    }
  }
}

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 akamai-ai-firewall-v2-inbound.
handler.export <string> - The name of the exported type. Value should be AkamaiAIFirewallV2InboundPolicy.
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.

configurationId (required) <string> - The configuration ID of the AI Firewall.
api-key (required) <string> - The API key for the AI Firewall.
applicationId <string> - The application ID to identify this usage of the AI Firewall (optional).
streamingAccumulation <object> - Configuration for accumulating and validating streaming responses.
- enabled <boolean> - Enable accumulation and validation of streaming responses. Defaults to true.
- eventsInterval <number> - Number of SSE events to accumulate before checking with Akamai (default: 5). Defaults to 5.
- checkIntervalMs <number> - Time interval in milliseconds for periodic checks (alternative to chunk count).
endpoints <string[]> - The endpoint shapes this policy applies to. Omit to apply to all (openai-chat, openai-responses, anthropic-messages).
onUnknownShape <string> - What to do when the request shape cannot be inspected. As a guardrail, this policy defaults to 'deny' (fail closed) so uninspectable content is never served. Allowed values are deny, skip. Defaults to "deny".
onError <string> - What to do when the Akamai detect call itself fails (invalid API key, rate limit, outage). 'block' (the default) fails closed and returns a 502 so unverified content is never served; 'allow' fails open and lets the request through without inspection. Allowed values are block, allow. Defaults to "block".

Using the Policy

Akamai AI Firewall

The Akamai AI Firewall policy sends prompts and completions to Akamai Firewall for AI and blocks content that your Akamai configuration denies. One inbound policy covers both directions: it scans the request before the provider call and the response afterward, including streaming responses.

Detection rules and their categories live in Akamai Control Center. The policy enforces rules configured to deny; rules configured only to alert do not block the request.

Configure the policy

Create or select an Akamai Firewall for AI configuration and API key. Declare the policy once in config/policies.json, then add the declaration to each application policy chain that should be protected. To protect new applications by default, include it in the team's policy template.


Code
{
  "name": "akamai-ai-firewall-v2-inbound",
  "policyType": "akamai-ai-firewall-v2",
  "handler": {
    "export": "AkamaiAIFirewallV2InboundPolicy",
    "module": "$import(@zuplo/runtime)",
    "options": {
      "configurationId": "your-configuration-id",
      "api-key": "$env(AKAMAI_AI_FIREWALL_API_KEY)"
    }
  }
}

When an application chain entry should inherit these credentials, omit the entry's options. Entry options replace the declaration's complete options object; they do not merge with it.

Options

Option	Default	What it does
`configurationId`	Required	Selects the Akamai firewall configuration.
`api-key`	Required	Authenticates to Akamai. The property name includes the hyphen.
`applicationId`	Unset	Supplies an optional Akamai application identifier.
`endpoints`	All shapes	Limits inspection to selected AI Gateway endpoint shapes.
`onUnknownShape`	`deny`	Denies or skips a request whose shape cannot be inspected.
`onError`	`block`	Blocks or allows traffic when the Akamai detection call fails.
`streamingAccumulation.enabled`	`true`	Enables response inspection for streaming requests.
`streamingAccumulation.eventsInterval`	`5`	Buffers this many stream events between checks.
`streamingAccumulation.checkIntervalMs`	Unset	Also runs checks on a timer when configured.

Unknown option keys and incomplete credentials are rejected. Invalid options fail closed so a broken chain never silently disables the guardrail.

Streaming behavior

For streaming responses, the gateway withholds each batch of events until the Akamai check passes. This prevents denied content from reaching the client, but the buffering and network check add latency. If a later batch is denied, the stream ends with a content-filter stop rather than changing the HTTP status of a response that has already started.

Block and failure behavior

A denied request or non-streaming response returns 400 in the request shape's native error format and includes the Akamai rule ID. Anthropic Messages uses an Anthropic-style error; Chat Completions and Responses use an OpenAI-style error. Provider error responses are not scanned.

Situation	Result
Options are invalid or incomplete	Request rejected before unguarded traffic can run.
The endpoint shape cannot be inspected	`400`, with code `guardrail_uninspectable`.
A recognized request body cannot be parsed	Request continues without input inspection.
A successful response body cannot be parsed	Response passes through without output inspection.
Akamai rejects the credentials, rate-limits the call, or is unavailable	`502`, with code `guardrail_unavailable`.
The endpoint is excluded by `endpoints`	Request passes through without inspection.

Setting onError to allow changes service failures to fail open. An expired credential can then leave the gateway returning successful responses without inspection, so monitor firewall findings and sudden drops in block volume.

Additional resources