Enhanced Debug is a default, secure, and feature-rich method for diagnosing requests that replaces older Pragma debugging. It uses a time-limited authentication token generated from a customer-defined secret key to prevent unauthorized access.

See also the Debug Mode match. It explains how you can control other functionality in your property based on whether a specific request is being debugged using enhanced debugging.

Before you begin

Review your configuration and perform the following steps if necessary:

Remove any Pragma debugging-specific code, such as the Remove Debug Info rule.
Remove any code related to passing a specific header to enable Pragma debugging.
If you are using WAF, disable Rule 699989 to strip Pragma request headers.

Implementation

Add the behavior and make sure the Enable slider is On. You can add it to these rules in your property:

The Default Rule. All requests processed by this property will support Enhanced Debug.
A custom top-level rule. You can add it in a custom rule that doesn’t have any parents and match criteria.

Features and options

Option	Description
Debugging Enabled	Enable enhanced debugging using the Akamai-Debug request header.
Debug Key	Specify the debug key to validate the debugging auth token when Akamai processes the request. You also use this debug key to generate the auth token. The debug key value needs to be a 64-byte hex string. To auto-generate a valid random string, click the refresh button. As a best practice, you can reuse the same debug key in your other properties.
Disable Pragma Debugging	Whether you want to allow Pragma-based debugging. This is disabled by default, meaning that the legacy debugging with the Pragma request header is no longer available. You should only enable Pragma debugging during a transition period, until you have updated all your systems to use Enhanced Debug.
Global Request Number	Specify whether you want to return the Global Request Number (GRN) in the Akamai-GRN response header for all requests, even if the request is not being debugged. For example: `Akamai-GRN: 0.25313217.1562625611.27bb4bb` If you want to return a GRN for all requests, remove any instances of the Global Request Number behavior from your property.

Generate the authentication token

To make an Enhanced Debugging request, generate an auth token with either:

Akamai Debug application.
Akamai's EdgeAuth software development kits (SDKs), available for multiple programming languages. See the README section for details on how to use the SDKs.

To generate the token, you need to provide these values:

The Debug Key value specified in the Enhanced Debug behavior.
A duration for which the token should be valid. This can range from 30 seconds to 1 day.

You can use the same token to debug multiple requests until it expires.

Debug your requests

To start debugging and receive comprehensive details in the response, pass the auth token and specify debugging options with your request.

Specify the auth token

You can pass the auth token either within the header or in a separate header or cookie. The debugging functionality is exactly the same in each method.

Akamai-Debug header. You can pass the auth token as the first value in the Akamai-Debug header:

Akamai-Debug: [auth-token] option [option…]

See this example with the cache and vars options:

Akamai-Debug: exp=1562789819~acl=%2f*~hmac=06b2aaac06fc420b172cfdaf227459dc2176f5d64e4b6f2648f01980768837cf vars cache

akamaidebugtoken cookie. You can pass the auth token in the akamaidebugtoken cookie, and pass only the debugging options in the Akamai-Debug header.

Akamai-Debug: option(s) Cookie: akamaidebugtoken=auth-token

See this example with the cache and vars options:

Akamai-Debug: vars cache Cookie: akamaidebugtoken=exp=1562789819~acl=%2f*~hmac=06b2aaac06fc420b172cfdaf227459dc2176f5d64e4b6f2648f01980768837cf

Note that the akamaidebugtoken cookie name is case-sensitive, and must be specified as lower-case.

📘
If you pass an invalid or expired auth token, a Akamai-Debug-Status response header is returned, indicating the specific auth token error. No other debugging response headers are returned.

Specify the Akamai-Debug header options

Enhanced Debugging offers a modern alternative to the legacy Pragma header debugging method. Instead of passing a long sequence of Pragma values, the Akamai-Debug header provides a concise, simpler alias.
Here’s how the two approaches compare:

Akamai-Debug value	Equivalent Pragma headers	Debug response headers returned
[any value]	akamai-x-get-request-id	X-Akamai-Request-ID Akamai-GRN
cache	akamai-x-cache-on, akamai-x-cache-remote-on, akamai-x-check-cacheable, akamai-x-get-cache-key, akamai-x-get-true-cache-key	X-Cache, X-Cache-Remote X-Check-Cacheable X-Cache-Key X-Cache-Key-Extended-Internal-Use-Only X-True-Cache-Key Edge-Cache-Tag Akamai-Cache-Status Akamai-Stage-Info-`` (multiple) Akamai-Cache-Info-`` (multiple)
ssl or tls	akamai-x-get-ssl-client-session-id	X-Akamai- SSL-Client-Sid Akamai-Connection-Info
vars	akamai-x-get-extracted-values	X-Akamai-Session-Info
client	akamai-x-get-client-ip	X-Akamai-Pragma-Client-IP Akamai-Client-Info
feo	akamai-x-feo-trace	X-Akamai-Transformed X-Akamai-FEO-`*` (multiple)
im or ro	akamai-x-ro-trace	X-Akamai-RO-`*` (multiple)
tags	akamai-x-get-cache-tags	Edge-Cache-Tag
all	All values above	All headers above
a2	x-akamai-a2-trace (not included with all)	x-akamai-a2-`*` (multiple)
brotli	akamai-x-get-brotli-status (not included with all)

As an example, specifying the following Akamai-Debug request header:
Akamai-Debug: cache vars

results in the same debug response headers being returned as if you passed this Pragma request header:
Pragma: akamai-x-get-request-id, akamai-x-cache-on, akamai-x-cache-remote-on, akamai-x-check-cacheable, akamai-x-get-cache-key, akamai-x-get-true-cache-key, akamai-x-get-extracted-values