Secure.allowlist_headers()

Enforce a case-insensitive allowlist for header names in headers_list.

Usage

Source

Secure.allowlist_headers(
    *,
    allowed=DEFAULT_ALLOWED_HEADERS,
    allow_extra=None,
    on_unexpected="raise",
    allow_x_prefixed=False,
    logger=None
)

Parameters

allowed: Iterable[str] = DEFAULT_ALLOWED_HEADERS

Base allowlist of header names (case-insensitive).

allow_extra: Iterable[str] | None = None

Additional names to allow, for example app-specific headers.

on_unexpected: OnUnexpectedPolicy = "raise"
Policy for headers not in the allowlist:
  • "raise": error on any name not in the allowlist (default).
  • "drop": remove unexpected headers (logs if logger is set).
  • "warn": keep unexpected headers but log a warning.
allow_x_prefixed: bool = False

If true, allows any header starting with "x-".

logger: logging.Logger | None = None
Optional logging.Logger used for warnings in "drop" and "warn" modes.

Returns

Secure
The same instance, for call chaining.

Raises

ValueError
If on_unexpected="raise" and any header is not in the allowlist.