Copy page

Akamai Firewall for AI Policy

Akamai Firewall for AI inspects responses produced by AI applications and detects threats such as sensitive data exposure, toxic content, and other policy violations.

This policy sends each upstream response to Akamai's detect endpoint before it's returned to the client. If Akamai returns a rule with a deny action, the response is replaced with a 403 Forbidden. Rules with an alert action (Akamai "Monitor" mode) are logged by default but allowed through, configurable via the onWarn setting.

Pair with the Akamai Firewall for AI - Inbound policy to also inspect incoming requests before they reach your handler.

Configuration

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

config/policies.json
{
  "name": "my-akamai-firewall-for-ai-outbound-policy",
  "policyType": "akamai-firewall-for-ai-outbound",
  "handler": {
    "export": "AkamaiFirewallForAiOutboundPolicy",
    "module": "$import(@zuplo/runtime)",
    "options": {
      "configurationId": "$env(AKAMAI_FIREWALL_FOR_AI_CONFIGURATION_ID)",
      "api-key": "$env(AKAMAI_FIREWALL_FOR_AI_API_KEY)",
      "capture": {
        "body": true,
        "headers": false,
        "url": false,
        "queryString": false
      },
      "onWarn": "log",
      "throwOnError": true
    }
  }
}

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-firewall-for-ai-outbound.
• handler.export <string> - The name of the exported type. Value should be AkamaiFirewallForAiOutboundPolicy.
• 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> - Your Akamai Firewall for AI Configuration ID. This is the ID of the configuration in the Akamai Control Center that defines which detection rules to apply.
• api-key (required) <string> - Your Akamai Firewall for AI API key, sent as the Fai-Api-Key header on each detect call.
• capture <object> - Controls which parts of the upstream response (and the originating request URL) are sent to Akamai for inspection. Akamai's detect endpoint receives the captured fields concatenated into a single labeled text payload as llmOutput.
  • body <boolean> - Include the response body. Only text-based content types (JSON, XML, form-encoded, text/*) are sent; binary bodies are skipped. The body is read from a clone of the response so the client still receives it unchanged. Defaults to true.
  • headers <boolean> - Include the response headers. By default Set-Cookie is stripped — see dangerouslyIncludeCookieHeader to override. Defaults to false.
  • url <boolean> - Include the originating request URL (origin and path, query string excluded). Useful as context for the response. Defaults to false.
  • queryString <boolean> - Include the originating request's query string. Query strings sometimes contain credentials or session tokens — leave this off unless you want Akamai to see them. Defaults to false.
  • dangerouslyIncludeAuthorizationHeader <boolean> - If headers is true, also include any Authorization or Proxy-Authorization headers on the response. Rarely set on responses but stripped by default for safety. Defaults to false.
  • dangerouslyIncludeCookieHeader <boolean> - If headers is true, also include the Set-Cookie header on the response. Off by default because Set-Cookie typically carries session credentials. Defaults to false.
• onWarn <string> - Behavior when Akamai returns a rule with action: "alert" (Akamai's Monitor mode). log writes a warning and lets the response through, block treats the alert like a deny, none is silent. Allowed values are log, block, none. Defaults to "log".
• throwOnError <boolean> - If true (the default), the policy throws when the Akamai detect call itself fails (network error, 5xx, malformed response). Set to false to fail open and allow the response through when Akamai is unreachable. Defaults to true.
• detectUrl <string> - Override the Akamai Firewall for AI detect endpoint URL. The literal {configurationId} is replaced with the configured ID. Defaults to https://aisec.akamai.com/fai/v1/fai-configurations/{configurationId}/detect. Useful for regional Akamai endpoints or for pointing tests at a mock server.

Using the Policy

Setup

1. In the Akamai Control Center, create a Firewall for AI configuration and note its Configuration ID.

2. Generate an API key for the configuration.

3. Add the credentials to your Zuplo project's environment variables (or paste them directly into the policy options):

   Code
   AKAMAI_FIREWALL_FOR_AI_CONFIGURATION_ID=your-configuration-id
   AKAMAI_FIREWALL_FOR_AI_API_KEY=your-api-key

4. Add the policy to any route whose responses should be inspected by Akamai.

What gets sent to Akamai

Akamai's detect endpoint accepts a single text string in llmOutput. The capture option controls which parts of the response are concatenated into that string:

Field	Default	Notes
body	true	Cloned before reading; only text content types (JSON, XML, form, text/*) are sent.
headers	false	Set-Cookie, Authorization, and Proxy-Authorization are stripped.
url	false	Origin and path of the originating request — useful as context for the response.
queryString	false	Off by default — query strings often contain credentials or session tokens.

Including credential headers

If you do want Akamai to see credential-bearing response headers, opt in explicitly:

Code
{
  "name": "akamai-firewall-for-ai-outbound",
  "policyType": "akamai-firewall-for-ai-outbound",
  "handler": {
    "export": "AkamaiFirewallForAiOutboundPolicy",
    "module": "$import(@zuplo/runtime)",
    "options": {
      "configurationId": "$env(AKAMAI_FIREWALL_FOR_AI_CONFIGURATION_ID)",
      "api-key": "$env(AKAMAI_FIREWALL_FOR_AI_API_KEY)",
      "capture": {
        "body": true,
        "headers": true,
        "dangerouslyIncludeCookieHeader": true
      }
    }
  }
}

Handling alert vs deny

Akamai rules can be configured with one of two actions:

• deny — the response is always replaced with a 403 Forbidden.
• alert — Akamai detected a match but configured the rule for monitoring only. The onWarn option controls how this policy reacts:
  • "log" (default) writes a structured warning to the Zuplo logs and lets the response through.
  • "block" treats alert the same as deny — useful in staging when rolling out new rules.
  • "none" silently lets the response through with no log line.

Failure modes

By default the policy is fail-closed: if the call to Akamai itself fails (network error, 5xx, malformed response), the policy throws and the original response is replaced with an error. This is the safe default for a security control. To fail open when Akamai is unreachable, set throwOnError: false.

Pair with the inbound policy

Add Akamai Firewall for AI - Inbound to the same route to also inspect requests before they reach your handler. The two policies share the same configuration shape.

Read more about how policies work