API Keys and Custom Headers

Analogy categoryAnalogies

API Key Authentication

An API key is a single static string an API issues to identify the calling application, often used for simpler rate-limiting and usage tracking rather than fine-grained user permissions. Postman's API Key auth type lets you specify a Key name (like x-api-key or apikey), the Key value, and whether it should be added to the request Header or the query string, generating the correct placement automatically without you touching the Headers or Params tab directly.

🏏

Cricket analogy: An API key is like a media organization's fixed accreditation number stamped on every press pass for the season, used mainly to track which outlet is filing how many reports rather than to distinguish individual journalists.

http

GET /v2/players/stats HTTP/1.1
Host: api.sportsdata.example.com
x-api-key: 8f3a1c9d2e7b4460a1f6d3c9e8b7a2f1
Accept: application/json

Header vs Query Parameter Placement

APIs place keys either in a custom header (most common and recommended, e.g. x-api-key) or in the query string (e.g. ?apikey=...); Postman's Add to dropdown in the API Key auth type switches between the two without changing the actual key value you typed. Header placement is generally preferred because query strings routinely get logged in server access logs, browser history, and proxy logs, exposing the key in plaintext long after the request completes.

🏏

Cricket analogy: Putting a key in a header versus a URL query string is like a stadium's private staff entrance versus writing your access code on a public noticeboard by the main gate — one is checked discreetly, the other is visible to anyone walking past.

Custom Headers Beyond Authentication

Not every custom header carries a credential — headers like Content-Type, Accept, X-Request-ID, and API-specific ones such as Stripe-Version or X-GitHub-Api-Version control response format, request tracing, and API versioning. Postman's Headers tab lets you add these manually, and many are auto-populated based on the request body type you choose (for example, selecting 'raw' with JSON in the Body tab automatically adds Content-Type: application/json).

🏏

Cricket analogy: An X-Request-ID header is like a unique delivery number stamped on a ball used only in that specific over, letting umpires trace exactly which delivery is being reviewed on DRS without confusing it with any other.

Postman automatically adds several headers behind the scenes (like Host, User-Agent, and Accept-Encoding) that don't appear in the Headers tab by default; you can reveal and override them by toggling 'Hidden' auto-generated headers at the bottom of the Headers tab.

API keys placed in the query string are far more likely to leak — they end up in server access logs, browser history, and any proxy or CDN logs along the request path. Prefer header-based API keys, and rotate any key that was ever sent as a query parameter.

API keys are static identifiers for the calling application, typically used for rate-limiting and usage tracking, not fine-grained user identity.
Postman's API Key auth type can place the key in either a header (e.g. x-api-key) or a query parameter via the Add to dropdown.
Header placement is preferred over query-string placement because URLs frequently get logged in plaintext across servers and proxies.
Custom headers like Content-Type, Accept, and X-Request-ID serve purposes beyond authentication, such as format negotiation and request tracing.
Postman auto-populates some headers (like Content-Type) based on the Body tab configuration.
Hidden, auto-generated headers (Host, User-Agent, etc.) can be revealed and overridden in the Headers tab.
Rotate any API key that was ever exposed via a query string, since it likely persists in logs beyond the request's lifetime.