Add custom HTTP headers to Prometheus scrapes

Use authorization, basic_auth, or oauth2 for their corresponding authentication schemes. For other request headers, use http_headers in the scrape job. Custom scrape headers were added in Prometheus 2.55.0; the older introduction of authorization does not imply support for arbitrary headers.

Send a bearer token

scrape_configs:
  - job_name: secure-app
    scheme: https
    static_configs:
      - targets: ['app.example.com:443']
    authorization:
      type: Bearer
      credentials_file: /etc/prometheus/token

Mount the token file where the Prometheus process can read it, restrict access, and configure CA trust when the endpoint uses a private certificate authority. Use the intended authentication block rather than trying to combine incompatible authentication mechanisms on the same request.

authorization is available from Prometheus 2.26.0. Check your installed version and its configuration reference; validate with a matching promtool before reload.

Send a custom header

scrape_configs:
  - job_name: custom-headers
    scheme: https
    static_configs:
      - targets: ['app.example.com:443']
    http_headers:
      X-Scope-OrgID:
        values: ['team-a']
      X-Custom-Header:
        values: ['my-value']

Use nonsecret routing values in values. The header configuration also supports secrets for values hidden in the displayed configuration and files for file-backed values. Redaction in a configuration page does not encrypt a secret stored in a file or repository.

Prometheus reserves headers that it manages itself; custom headers cannot overwrite them. Configure Authorization through its supported authentication settings rather than the custom-header map. Do not assume an arbitrary Host or content-negotiation override will be accepted or behave like a normal application header.

Work with an older server

Prefer a supported upgrade when feasible. Otherwise, a reverse proxy can receive the scrape and add the required upstream header. Restrict access to that proxy: a proxy holding a credential can give callers access to the protected endpoint. Verify the proxy's TLS trust and ensure its logs do not expose secrets.

Common questions

Can each target use a different header? Header settings belong to a scrape job and are not templated from target labels. Split targets into jobs when they need different values or authentication.

Why does the scrape return 401? Test the intended URL and credential from the same network path, then compare the actual job configuration, token file permissions, expiry, proxy behavior, and authorization scope. Keep secrets out of shell history and diagnostic output. A successful request from your laptop does not prove that the Prometheus Pod can reach or authenticate to the endpoint.

References

• Prometheus HTTP client configuration
• Prometheus release history