Skip to main content

Credentials and Headers

Collections support collection-level credentials and shared headers that apply to every proxy in the collection. Individual proxies can override these settings for their specific endpoint.

Collection-level credential​

Attach a credential to the collection to authenticate all outbound upstream requests:

  1. Open the collection and click Edit.
  2. In the Credential field, select a stored credential.
  3. Click Save.

Zerq injects the credential automatically on every backend request made by any proxy in this collection. This avoids repeating the same credential on each individual proxy.

Credential scoping rules:

  • If a proxy has its own credential attached, it overrides the collection credential for that endpoint only.
  • If a proxy has no credential, the collection credential is used.
  • If neither has a credential, the request is forwarded without any outbound authentication.

This scoping allows a collection to have a default backend API key, while one or two proxies with elevated permissions use a different credential.

Custom headers​

Custom headers are injected into every upstream request across all proxies in the collection. Two modes are supported:

ModeBehaviourUI badge
StaticLiteral value sent on every requestPurple badge
Env VarValue resolved from a named container environment variable at runtimeBlue badge

Adding headers​

  1. In collection settings, open the Headers section.
  2. Click Add Header.
  3. Enter the header Key (e.g. X-Internal-Key).
  4. Choose Static or Env Var:
    • Static — enter the value directly
    • Env Var — enter the environment variable name (e.g. INTERNAL_API_KEY)
  5. Click Save.

When to use Env Var mode​

Env Var mode avoids storing secrets in the database. Set the environment variable on your gateway container:

INTERNAL_API_KEY=secret_value

Then reference INTERNAL_API_KEY in the header configuration. The gateway resolves it at request time. This is the recommended approach for API keys, auth tokens, and any header value that varies by environment.

Proxy-level overrides​

Proxies can define their own headers in addition to (or instead of) the collection headers. Proxy headers are merged with collection headers at request time. If the same key exists at both levels, the proxy value takes precedence.

Practical guidance​

  • Use collection-level credentials for the shared backend auth (e.g. one API key for all endpoints in the service).
  • Use Env Var mode for any value that differs between environments (dev/staging/production).
  • Use proxy-level headers only for endpoint-specific metadata (e.g. a single endpoint needs an extra X-Resource-Type header).
  • Avoid duplicating the same header at both collection and proxy level — it adds noise without benefit.
  • Collections — collection lifecycle and settings
  • Create a Proxy — step 3 of the wizard covers proxy-level headers
  • Credentials — all credential types and how they're encrypted