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.

Logic

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).

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.

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

Configuration

General behavior

• Only one list can be enabled at a time.
• Lists are disabled by default and cannot be enabled when empty.

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 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 headers

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 practices

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.

Examples

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