Skip to main content

Schema Overview

EaaS (Edge as a Service) is a tenant configuration system for Akamai's edge platform. Each tenant — typically identified by a hostname — gets a single JSON configuration file that controls delivery behavior (caching, routing, headers) and security policies (WAF rules, IP blocking, rate limiting).

When a request arrives at the Akamai edge, an EdgeWorker reads the tenant's configuration and applies it in real time. Changes take effect on the next request — no property activation or deployment step needed.

Configuration Structure​

A tenant configuration has four top-level sections. Only configure what you need — all are optional.

tenant.json
├── tenant_id            Identifies the tenant in logs and analytics
├── lists                Named value lists referenced in match rules
├── delivery_config
│   ├── version          Always "1.0"
│   ├── onClientRequest
│   │   └── features     Caching, routing, headers, redirects...
│   ├── onOriginResponse
│   │   └── features     Response headers, cache tags...
│   └── onClientResponse
│       └── features     Client-facing headers, compression...
└── security_config      WAF rules, IP blocking, rate limiting

Minimal Working Config​

The smallest useful config routes traffic to your origin:

JSON
{
"tenant_id": "my-app",
"delivery_config": {
  "version": "1.0",
  "onClientRequest": {
    "features": {
      "route": {
        "rules": [{
          "args": { "originId": "default_eaas" },
          "pm_variables": {
            "RT_ORIGIN_DNS": "origin.example.com",
            "RT_ORIGIN_HOST_HEADER": "origin.example.com"
          }
        }]
      }
    }
  }
}
}

Add caching, security, headers, and other features as needed. Here's a more complete example:

JSON
{
"tenant_id": "my-app",
"delivery_config": {
  "version": "1.0",
  "onClientRequest": {
    "features": {
      "caching": {
        "rules": [{
          "matchAll": { "paths": ["/api/*"] },
          "args": { "ttl_seconds": 3600 }
        }]
      },
      "route": {
        "rules": [{
          "args": { "originId": "default_eaas" },
          "pm_variables": {
            "RT_ORIGIN_DNS": "origin.example.com"
          }
        }]
      }
    }
  }
},
"security_config": {
  "deny_groups": ["SQL-INJECTION-ANOMALY", "XSS-ANOMALY"]
}
}

This config caches /api/* responses for one hour, routes to a custom origin, and enables SQL injection and XSS protection.

Rule Structure​

Most features use a rule-based structure — a list of rules where the first match wins:

JSON
{
"feature_name": {
  "rules": [
    {
      "matchAll": { "paths": ["/api/*"] },
      "args": { /* feature-specific options */ }
    }
  ]
}
}

Some features also accept a simple value (e.g., "connectTimeout": 5000) when no conditional logic is needed.

Match Conditions​

Match conditions determine when a rule fires. Three operators control how conditions combine:

OperatorBehavior
matchAllAll conditions must match (AND)
matchAnyAny condition must match (OR)
matchNoneNo conditions must match (NOT)

See Match Conditions for the full list of conditions and examples.

Available Features​

Each event handler supports different features. Click a feature name to see its full documentation.

FeatureEvent HandlersDescription
cachingonClientRequestControl how content is cached with flexible TTL rules and behaviors
downstreamCachingonClientRequestControl how edge servers instruct client browsers and intermediate proxies to cache content.
compressiononClientRequestonClientResponseEnable gzip compression for specified content types to reduce bandwidth
setVariableonClientRequestonOriginResponseonClientResponseSet custom variables that can be used for logging and conditional processing
removeVaryonClientRequestRemove or control the Vary response header to improve cache efficiency
tieredDistributiononClientRequestConfigure tiered distribution settings for optimized content delivery
routeonClientRequestRoute requests to different origins based on path patterns
redirectonClientRequestConfigure HTTP redirects with custom status codes and destination URLs
allowPostonClientRequestEnable or disable POST requests with rule-based conditions
allowPutonClientRequestEnable or disable PUT requests
allowDeleteonClientRequestEnable or disable DELETE requests with rule-based conditions
allowPatchonClientRequestEnable or disable PATCH requests
respondWithonClientRequestonClientResponseReturn custom responses without contacting the origin
setHeadersonClientRequestonClientResponseonOriginResponseAdd, modify, or remove HTTP headers in requests and responses
http2onClientRequestNo longer supported in tenant file. HTTP/2 is enabled by default for all tenants.
http3onClientRequestNo longer supported in tenant file. HTTP/3 is enabled by default for all tenants.
webSocketsonClientRequestEnable WebSocket support with conditional rules
chunkedTransferEncodingonClientRequestEnable or disable chunked transfer encoding
hstsonClientRequestConfigure HTTP Strict Transport Security headers to enforce secure connections
originIpAclonClientRequestConfigure origin IP access control lists. [https://techdocs.akamai.com/origin-ip-acl/docs/welcome](https://techdocs.akamai.com/origin-ip-acl/docs/welcome)
breadcrumbsonClientRequestEnable breadcrumb tracking for debugging and monitoring
cacheTagonOriginResponseTag cached content for easier invalidation
tenantTagonClientRequestLegacy tenant identification. Use top-level tenant_id instead
readTimeoutonClientRequestConfigure timeout for reading from origin with rule-based support
firstByteTimeoutonClientRequestConfigure timeout for first byte from origin with rule-based support
connectTimeoutonClientRequestConfigure timeout for establishing connection to origin (integer seconds, or rules object for conditional timeouts)

See Delivery Configuration for detailed documentation and examples for each feature.

Tenant Identification​

The tenant_id property identifies the tenant in datastream logs and analytics. It is defined at the top level — outside delivery_config and security_config.

tenant_id accepts either a single string or an array of up to 5 strings. Each value must be at most 20 characters long and cannot contain "|" or "," characters.

For a single tenant:

JSON
{
"tenant_id": "my-tenant"
}

For multiple tenant IDs (up to 5):

JSON
{
"tenant_id": ["tenant-a", "tenant-b", "analytics-group"]
}

View Schema Definition

Migration from tenantTag

The tenant_id property replaces the deprecated tenantTag feature that was previously nested inside delivery_config.onClientRequest.features. Unlike tenantTag, tenant_id is a top-level property.

Lists​

The lists property defines named lists of string values that can be referenced inside match conditions using the {{list.<key>}} syntax. This lets you define a set of values once and reuse it across multiple rules, avoiding duplicated values across rules and making updates easier.

JSON
{
"lists": {
  "blocked_ips": ["192.0.2.0/24", "198.51.100.0/24"],
  "api_paths": ["/api/v1/*", "/api/v2/*"],
  "bot_agents": ["curl/7*", "python-requests*"]
},
"delivery_config": {
  "version": "1.0",
  "onClientRequest": {
    "features": {
      "respondWith": {
        "rules": [{
          "matchAll": { "ipv4": "{{list.blocked_ips}}" },
          "args": { "status": 403, "body": "Forbidden" }
        }]
      },
      "caching": {
        "rules": [{
          "matchAll": { "paths": "{{list.api_paths}}" },
          "args": { "ttl_seconds": 60 }
        }]
      }
    }
  }
}
}

List references work in any match condition value — strings, arrays, and header/query objects. You can also mix list references with inline values:

JSON
{
"matchAll": {
  "ipv4": ["{{list.blocked_ips}}", "203.0.113.0/24"],
  "reqheader": { "User-Agent": "{{list.bot_agents}}" }
}
}

Lists can also be defined in a shared common config (common.json), making them available across all tenants. Local tenant lists take precedence over common lists when both define the same key. See the Release 1.12.0 notes for full details on common config setup.

View Schema Definition

Next Steps​