Manage header access list

Header access lists let you control traffic by allowing or blocking requests based on HTTP headers or header fingerprints. This helps secure your store by filtering unwanted requests (e.g., bots, scrapers) or strictly allowing only trusted clients.

Logicri:link

You can define header rules in two modes:

Block list

Blocks requests if a specified header contains the given string (case-insensitive, partial match). Any request containing the listed headers or values is denied (HTTP 403).

You can specify multiple values for the same header name. In this case, the rule applies an OR condition across all values for that header. For example, if you add:

• Name: X-Client-Region, Value: US
• Name: X-Client-Region, Value: AU

The logic is equivalent to:

if (header['X-Client-Region'].includes('US') || header['X-Client-Region'].includes('AU')) {
    // Rule matches
}

This allows you to match requests from any region listed, without needing separate rules for each value.

Use for: broadly blocking bots, scrapers, or requests from certain regions, networks or providers.

Allow list

A request must satisfy all Allow Header rules (exactly matches the provided string) to be permitted. Any mismatch results in blocking.

You can specify multiple values for the same header name. In this case, the rule applies an AND condition across all values for that header. For example, if you add:

• Name: X-Client-Region, Value: US
• Name: X-Client-Region, Value: AU

The logic is equivalent to:

if (header['X-Client-Region'] !== 'US' && header['X-Client-Region'] !== 'AU') {
    // Rule matches
}

Use for: allow list specific clients, TLS fingerprints, or networks (e.g., for whitelisting your third party proxy like CloudFlare, Akamai). Read more in Using an External Proxy with Alokai

Configurationri:link

General behavior

• Only one list can be enabled at a time.
• Lists are disabled by default and cannot be enabled when empty.
• Changes (adding, removing, enabling, or disabling) may take a few minutes to propagate.

Steps

• Choose the list type you want to use: Allowed or Blocked.
• Add entries to the list. Each entry requires a header name and value.
• Enable the list once it contains the rules you want to enforce.

Notes

• You can add entries to a list regardless of whether it is currently enabled or disabled.
• To update an entry, delete it first and then add a new one - editing is not supported.
• To remove the last element from a list, you must disable the list first.
• Entries with header names longer than 126 characters or values longer than 256 characters are not allowed.
• Allowed characters for names: a-z, A-Z, 0-9, -, _ (names cannot start or end with - or _).
• Allowed characters for values: a-z, A-Z, 0-9, and _ :;.,\/"'?!(){}[]@<>=-+*#$&\|~^%`.

Pre-defined headersri:link

Beyond standard HTTP headers, you can leverage advanced request filtering using pre-defined headers that Alokai@Edge automatically adds:

This enables you to build geo, network, or fingerprint-based allow/block lists — for example, blocking all traffic from suspicious ASNs or allowing only requests from specific TLS profiles.

Best practicesri:link

Use low-cardinality headers or fingerprints

• Choose headers that have a limited, predictable set of values (e.g., X-Client-Ja3: e7d705a3286e19ea42f587b344ee6865, X-Custom-Token: trusted-client).
• This avoids unnecessary cache fragmentation and makes rules easier to maintain.

Block only what is necessary

• Apply blocked lists to deny known malicious or unnecessary headers, such as debug flags or obsolete testing headers.
• Avoid creating broad rules that could interfere with legitimate traffic.

Don’t rely on User-Agent for security

• User-Agent strings are highly variable, easy to spoof, and filtering on them may block legitimate clients or crawlers (e.g., Googlebot).

Avoid blocking common browser headers

• Rejecting headers like Accept-Language or Referer can break normal functionality for end users. Limit blocking to headers you explicitly know are problematic.

Keep lists maintainable

• Review and update entries regularly. Remove obsolete rules that are no longer needed to prevent false positives and reduce operational overhead.

Examplesri:link

Correct usage

Allowed list:

• Name: X-Client-Ja3, Value: e7d705a3286e19ea42f587b344ee6865
• Name: X-Client-Region, Value: US
• Name: X-Custom-Token, Value: trusted-client

Blocked list:

• Name: User-Agent, Value: BadBot
• Name: X-Client-Ja3, Value: 6734f37431670b3ab4292b8f60f29984
• Name: X-Client-Region, Value: RU