Akamai EdgeWorkers runs JavaScript in the request and response path at the edge. That makes it useful for routing, headers, cache decisions, personalization, lightweight responses, and API-adjacent logic. It also means a small code change can affect a large amount of traffic before the request reaches your origin.
Akamai EdgeWorkers Security Best Practices: The Short Answer
If you only remember ten things, use these:
- Know exactly which event handler runs your code. Security assumptions change depending on whether logic runs before cache lookup, before the origin, before caching a response, or before the client receives it.
- Treat client-controlled values as untrusted. Validate paths, query strings, cookies, headers, methods, and any value used for routing, caching, or policy decisions.
- Keep authorization authoritative at the application or dedicated policy layer. Edge logic can add useful checks, but object ownership and sensitive business authorization should not depend on a spoofable header or a single edge condition.
- Review cache behavior as a security control. Personalization, authentication, and cache-key changes can create cross-user data exposure if the key does not vary on the right data.
- Use sub-requests deliberately. Restrict destinations, validate returned data, handle timeouts, and budget for their wall-time and response-size limits.
- Separate normal secrets from EdgeKV access tokens. Do not place generic API keys or private credentials in bundles. For EdgeKV, follow Akamai's token model and access-group guidance rather than treating the token like a normal external bearer secret.
- Design for platform limits. CPU, memory, wall time, sub-request counts, bundle size, and response limits are part of the security and resilience model.
- Choose failure behavior intentionally. Know whether an EdgeWorkers error should fail closed, continue, or trigger a defined failover path.
- Log enough to investigate, but not enough to leak data. Use DataStream 2 or debug tooling and redact credentials, cookies, tokens, personal data, and sensitive payloads.
- Monitor the APIs behind the edge. Edge code can shape traffic, but it does not by itself prove that downstream authorization, data exposure, and business workflows are safe.
What Changed in EdgeWorkers in 2026
This guide was refreshed against Akamai's current documentation and August 2026 release notes. Several changes make observability and operational review more useful than in older EdgeWorkers guides.
| 2026 change | Security / operations impact |
|---|---|
| Aug. 26: uncaught JavaScript exception logging | A log-uncaught-exception bundle setting can send uncaught exceptions to a DataStream 2 endpoint, improving failure visibility without relying only on request-level debugging. |
| Aug. 26: new sub-request report | The report shows sub-request executions, wall times, and response body sizes by hostname, which is useful for spotting slow dependencies and unexpected outbound patterns. |
| July 28: wall-time report | Teams can more directly review wall-time behavior against the resource tier chosen for the EdgeWorker. |
| Feb. 23: report accuracy update | Akamai notes that EdgeWorkers reports began including more accurate usage information and currently have about five minutes of report latency. |
| Current resource tiers | Basic, Dynamic, and Enterprise Compute have different memory, CPU, wall-time, and sub-request ceilings. Capacity assumptions should be tested against the actual tier, not copied from an old example. |
Start With an Edge-Specific Threat Model
EdgeWorkers is not just “JavaScript hosted somewhere else.” It executes at specific points in Akamai's delivery flow, so the main security question is what trust decision does this code make at that point in the request?
| Trust boundary | What to review | Typical failure |
|---|---|---|
| Client → edge | Headers, cookies, URL, query, method, body where supported, identity signals | Spoofed input changes routing, cache behavior, or a security decision |
| Edge → origin | Origin host, forwarded headers, authentication material, correlation data | Untrusted input is forwarded as if it were trusted internal context |
| Origin → edge/cache | Status, headers, cacheability, personalized response variation | Sensitive response becomes cacheable or internal metadata reaches the client |
| Edge → sub-request target | Destination allow-list, method, parameters, timeout, returned content | Unexpected dependency, slow call, oversized response, or unsafe data reuse |
| Edge → EdgeKV | Namespace, group, data classification, token governance | Over-broad organizational access or sensitive data stored where it is unnecessary |
| Edge → logging / SIEM | Fields logged, retention, correlation IDs, access to logs | Credentials or personal data become a secondary exposure in telemetry |
Security Review by EdgeWorkers Event Handler
Akamai's code bundle model uses event handlers including onClientRequest, onOriginRequest, onOriginResponse, onClientResponse, and responseProvider. Reviewing them as one generic “edge function” misses important differences.
| Handler | Where it runs | Security questions |
|---|---|---|
onClientRequest | When the request arrives, before cache lookup | Can untrusted input affect the cache key, route, redirect, headers, or later policy? Are values normalized before comparison? |
onOriginRequest | Just before a cache-miss request is sent to the origin | Which headers are added or removed? Can the origin mistake client-controlled data for trusted edge context? Is origin selection constrained? |
onOriginResponse | As the origin response is created, before it is cached | Are internal headers removed? Is cacheability safe for authenticated or personalized content? Note that normal inline handlers do not read the response body. |
onClientResponse | Just before the response is sent to the client | Are security headers correct? Are internal or debug headers stripped? Does client-visible behavior match the intended policy? |
responseProvider | Generates the response instead of sending the normal origin request | Are sub-request destinations trusted? Are status, headers, body, and failure cases bounded? Is generated content safe and correctly cacheable? |
Akamai also supports event-bypass variables. If your property can bypass a handler, include the bypass path in threat modeling and tests. A control is only reliable if you know when it executes and when it intentionally does not.
Validate Inputs and Treat Cache Design as Security Design
Headers, cookies, query parameters, paths, and client-supplied identity hints should be treated as untrusted unless you can prove they were set and protected by a trusted upstream control. Validation should be narrow: allow expected formats, cap length, normalize case/encoding where appropriate, reject ambiguous values, and avoid copying user input into privileged internal headers.
Do not let personalization silently become cross-user caching
The most serious edge mistakes often come from combining personalization with caching. If a response varies by user, tenant, role, region, experiment, or entitlement, the cache key and cacheability rules must preserve that separation. Review both the happy path and fallback behavior.
When code in onClientRequest uses fetched content to modify the original request's cache key, Akamai documents special purge implications. Treat cache-key design, purge behavior, and incident rollback as one control rather than three unrelated operational tasks.
Secure HTTP Sub-Requests and Origin Dependencies
EdgeWorkers can make asynchronous HTTP sub-requests. Akamai's current documentation says these sub-requests use HTTPS, operate within platform restrictions, and are subject to resource-tier limits. That makes dependency design part of the security review.
Constrain destinations
Use known hostnames and avoid building a security-sensitive destination from unchecked user input. Treat destination selection like SSRF-sensitive code even when platform routing limits reduce the attack surface.
Bound time and size
Know your tier's sub-request wall-time, count, concurrency, and response-size limits. A dependency that is safe at normal latency can become a reliability problem under failure.
Validate returned content
Do not assume a successful HTTPS fetch means the returned JSON, headers, or status is safe to reuse. Validate the structure and handle missing or unexpected fields.
Observe dependency behavior
Use the 2026 sub-request report to review hostname-level execution counts, wall time, and body sizes, then investigate unexpected growth or new dependencies.
EdgeKV Security: Use the Akamai Token Model Correctly
EdgeKV deserves more precise guidance than “never put a token in the bundle.” Akamai's EdgeKV design uses an EdgeKV-specific access token for namespace access from an EdgeWorkers function, and the token value is explicitly used by the code bundle. Akamai also states that the token cannot be used outside the customer's account and that information inside the token is not considered private or confidential.
That does not mean EdgeKV access should be casual. The security boundary is organizational access, namespace permissions, group assignment, data classification, and revocation.
| Control | Current Akamai guidance / practical action |
|---|---|
| Token lifecycle | Tokens created on or after September 3, 2024 do not expire; they refresh automatically until revoked. Older tokens can still expire and should be replaced before expiry. |
| Group isolation | Use the same Akamai Control Center access-group ID for the EdgeKV namespace and the EdgeWorker ID that uses it. This reduces the chance that an unauthorized internal user can indirectly retrieve a token via a bundle. |
| Namespace permissions | Avoid the default “all account access groups” model when the namespace should be restricted. Apply granular access that matches ownership. |
| Namespace names | Do not put private or confidential organizational information in namespace names; Akamai explicitly recommends against it. |
| Data classification | Store only data that genuinely needs edge access. Keep secrets, regulated data, or sensitive user records out unless the architecture and governance explicitly require and protect them. |
| Revocation | Revoke a token when its organizational trust boundary is no longer appropriate or it has been exposed across internal boundaries. |
Resource Limits Are Part of the Security Model
Edge code that is logically correct can still fail under real load if it assumes unlimited CPU, wall time, memory, or dependency calls. Akamai currently offers Basic, Dynamic, and Enterprise Compute tiers with different ceilings.
| Per inline event handler | Basic | Dynamic | Enterprise |
|---|---|---|---|
| Maximum memory | 1.5 MB | 2.5 MB | 4 MB |
| Maximum CPU time | 10 ms | 20 ms | 70 ms |
| Maximum wall time | 4 s | 5.5 s | 10 s |
| Sub-requests per handler | 2 | 4 | 10 |
| Parallel sub-requests | 2 | 4 | 10 |
Current global product limits also include a 512 KB compressed / 1 MB uncompressed code bundle, along with account-level limits for IDs, versions, and activations. Treat these limits as engineering constraints that should be tested in staging and monitored in production, especially when code performs multiple sub-requests or processes variable-size input.
Do not copy these numbers into a permanent architecture standard without re-checking Akamai's documentation. Limits can change and may also depend on contract or product configuration.
Choose Failure Behavior Intentionally
By default, Akamai documents that an EdgeWorkers execution failure halts the request. EdgeWorkers can also be configured to continue on error, and Akamai documents alternative handling through Property Manager and Site Failover.
The security decision is not simply “fail open or fail closed.” Ask what the EdgeWorker is doing:
- Security gate: continuing may bypass a protection decision, so failure should usually be conservative.
- Optional personalization: continuing to a safe default experience may be better than failing the entire request.
- Routing dependency: define an explicit fallback origin or failover path rather than relying on accidental behavior.
- Header enrichment: decide whether the origin can safely operate when the enrichment is missing.
Test the exact behavior for syntax errors, runtime exceptions, timeouts, failed sub-requests, malformed responses, and resource-limit breaches. Akamai's upload validation can catch some bundle problems, but its documentation notes that logical and runtime errors still require testing.
Logging and Monitoring: Use 2026 Capabilities Without Leaking Data
EdgeWorkers logging can be delivered through enhanced debug headers or DataStream 2. Akamai's current documentation also supports log-level controls and, as of August 26, 2026, uncaught-exception logging to DataStream 2.
The logging module is for investigation, not payload archival. Akamai documents a 1,024-byte maximum JavaScript log size per event handler and explicitly warns against putting sensitive data in log output.
| Monitor | Why it matters | Useful signal |
|---|---|---|
| Execution status / errors | Shows broken releases and runtime exceptions | Error rate by EdgeWorker ID and version |
| Wall time | Highlights dependencies or paths approaching tier limits | Wall-time distribution and outliers |
| Sub-requests | Shows dependency growth and unexpected hostnames | Count, hostname, wall time, body size |
| Origin status | Detects routing or header changes that damage the backend | 5xx, timeout, and origin-specific error changes after activation |
| Cache behavior | Finds personalization leakage and unexpected misses/hits | Cache-key change correlated with user/tenant behavior |
| API security events | Shows threats that remain valid-looking at the edge | BOLA, sensitive response data, automation, business-flow abuse |
Preserve or create a safe correlation ID that can be followed across Akamai, the origin, application logs, API security, and SIEM. Do not copy authentication headers or raw sensitive payloads just to make correlation easier.
Where EdgeWorkers Security Ends and Runtime API Security Begins
EdgeWorkers is a programmable edge-compute layer. It can validate inputs, normalize traffic, modify headers, route requests, generate responses, and apply custom logic. It is not a substitute for knowing whether the downstream API's authorization and business behavior are correct.
Examples that need application/runtime context include:
- a valid authenticated user reading another tenant's object;
- a legitimate token slowly enumerating customer records;
- a backend release adding sensitive fields to an API response;
- a valid workflow being automated at harmful scale;
- an AI agent invoking APIs in an unusual sequence under a valid service identity;
- shadow or deprecated APIs that remain active behind the edge.
Ammune can complement EdgeWorkers with runtime API discovery, request and response inspection, sensitive-data visibility, behavioral analysis, business-logic detection, enforcement options, and SIEM-ready security evidence. The practical model is edge control + authoritative backend authorization + runtime API visibility, not one product trying to replace the others.
Related Ammune guides: Real-Time API Threat Detection, API Key Security Best Practices, JWT API Security Best Practices, Per-User API Rate Limiting and Throttling, and API Visibility for AI Agents.
Production Security Checklist for Akamai EdgeWorkers
Use this as a release gate or quarterly review. A “yes” should be supported by code, configuration, tests, or monitoring evidence.
| Review item | Evidence to request |
|---|---|
| Purpose and owner are documented | EdgeWorker ID, owning team, property, use case, data classification |
| Event handlers are explicitly mapped | List of implemented handlers plus bypass conditions |
| Untrusted input is allow-listed / bounded | Unit tests for malformed, missing, oversized, duplicate, and encoded inputs |
| Backend authorization remains authoritative | Negative authorization tests that do not depend only on edge-added headers |
| Cache variation is safe | Two-user / two-tenant tests proving personalized responses cannot cross boundaries |
| Sub-request destinations are controlled | Known host list, timeout tests, error tests, size tests |
| EdgeKV is least-privileged | Namespace + EdgeWorker group IDs, token lifecycle, data inventory, revocation procedure |
| Generic secrets are not exposed | Bundle review and log review for credentials/private material |
| Resource-tier assumptions are tested | CPU/wall-time/sub-request behavior under worst expected input and dependency latency |
| Failure behavior is intentional | Documented continue-on-error / failover choice with security rationale |
| Rollback is tested | Known last-good version and activation rollback procedure |
| Logs are useful and minimized | DataStream/debug fields, retention, access, redaction rules |
| 2026 monitoring is enabled where useful | Wall-time, sub-request reporting, uncaught-exception logging as appropriate |
| Downstream APIs are observable | API inventory, identity/object/response context, sensitive-data and behavior monitoring |
Primary Sources and Freshness Notes
Last reviewed: September 14, 2026. Akamai product behavior can change. The following primary sources were used to refresh the technical claims in this guide:
- Akamai EdgeWorkers: Code bundle format — current event-handler model.
- Akamai EdgeWorkers: Event handler functions — handler timing, methods, and bypass behavior.
- Akamai EdgeWorkers: Content transformation — response-body access limitations and responseProvider behavior.
- Akamai EdgeWorkers: Resource tier limitations — current memory, CPU, wall-time, and sub-request limits.
- Akamai EdgeWorkers: Product limits — bundle and account/product limits.
- Akamai EdgeWorkers: Error handling — default errors, continue-on-error, and failover options.
- Akamai EdgeWorkers: JavaScript logging — DataStream 2/debug delivery, log limits, and sensitive-data warning.
- Akamai EdgeWorkers: Aug. 26, 2026 release notes — uncaught-exception logging and sub-request report.
- Akamai EdgeKV: Access token best practices — current token lifecycle.
- Akamai EdgeKV: Manage access — group and namespace access guidance.
Frequently Asked Questions
What is the most important Akamai EdgeWorkers security practice?
Know which event handler executes the logic and what trust decision it makes there. Then validate all client-controlled input, protect cache behavior, keep backend authorization authoritative, test failure paths, and monitor the deployed EdgeWorker against its resource limits.
Can EdgeWorkers read and modify an origin response body?
Normal inline handlers such as onOriginResponse and onClientResponse do not have access to the response body. Akamai documents content-transformation patterns that use responseProvider together with HTTP sub-requests when body content must be fetched and transformed.
Should EdgeKV access tokens be treated like normal API secrets?
Not exactly. Akamai's EdgeKV token model is account-bound and its documentation says token information is not considered private or confidential. Newer tokens auto-refresh until revoked. Security should focus on access-group isolation, namespace permissions, revocation, and data classification. Generic API keys, bearer tokens, OAuth client secrets, and private keys should still be handled as secrets.
What happens when an EdgeWorkers function fails?
Akamai documents that the request is halted by default when an EdgeWorkers execution error occurs. Teams can configure continue-on-error or use Property Manager and Site Failover for alternative behavior. The right choice depends on whether the function is a security gate, optional personalization, routing logic, or another use case.
What should teams monitor in EdgeWorkers in 2026?
Monitor execution errors, wall time, sub-requests, origin failures, cache behavior, version changes, and API security signals. Akamai's August 2026 updates added uncaught-exception logging to DataStream 2 and a sub-request report with execution, wall-time, and response-size data grouped by hostname.
Can EdgeWorkers replace runtime API security?
No. EdgeWorkers can enforce useful edge logic, but downstream APIs can still have BOLA, sensitive-data exposure, business-logic abuse, shadow endpoints, and valid-token misuse. Runtime API visibility should complement edge logic and authoritative backend authorization.
Secure the edge and keep visibility into the APIs behind it
Ammune can complement Akamai EdgeWorkers with runtime API discovery, request and response inspection, sensitive-data visibility, behavioral analysis, enforcement options, and SIEM-ready evidence.