# Custom auth header (optional)

## Custom auth header (optional)
If your receiver sits behind a gateway or reverse proxy that requires
a fixed authentication header — API key, bearer token, service
credential — you can configure Mercura to send one on every delivery.
When creating or editing a subscription, set:
- **Auth header name** — e.g. `X-API-Key`, `Authorization`
- **Auth header value** — e.g. `sk_live_abc123`, `Bearer eyJhbGci…`

Mercura then attaches that header to every `POST` **on top of** the
HMAC signature — the signature is still your authoritative source of
truth. Treat the custom header as a coarse gateway filter, not as a
replacement for verifying the signature.
The header value is never returned by any read endpoint — GET
responses expose only the header **name** and a `has_auth_header_value`
boolean so the admin UI can show "configured" without leaking the
secret. To rotate the value, `PATCH` the subscription with a fresh
`auth_header_value` (both fields must be sent together); to remove
the header entirely, `PATCH` both fields to `null`.
The following prefixes are reserved and rejected — they would collide
with Mercura's own delivery metadata:
- `Mercura-*`
- `Content-*`
- `User-Agent`
- `Host`

`Authorization` is intentionally NOT reserved — using
`Authorization: Bearer …` is a primary use case.

Version: 1.33.0