API & webhooks

API HTTP Headers: Build the Request the Endpoint Expects

Choose request headers for representation, authentication, and API-specific behavior while avoiding duplicate credentials and browser-controlled fields.

By Uddhav Gopani, FounderPublished 27 September 2026Updated 29 September 2026

Choose headers by their role in the request

HTTP headers communicate information about a request or response alongside the URL and body. For an API call, start with the headers the endpoint actually documents. Adding a large collection of copied headers can hide the intended authentication scheme, trigger an unnecessary preflight or send a content type that disagrees with the body.

For a JSON write, Content-Type describes the body being sent, while Accept expresses the response formats the client can handle. An Authorization header supplies the documented credential. These fields answer different questions and should not be used as interchangeable switches for making a request work.

Construct one deliberate set of JSON request headers

function jsonRequestHeaders(token) {
  const headers = new Headers({
    Accept: "application/json",
    "Content-Type": "application/json"
  });
  if (token !== undefined) {
    if (typeof token !== "string" || !token || /\s/.test(token)) {
      throw new Error("Use a nonempty token without whitespace.");
    }
    headers.set("Authorization", `Bearer ${token}`);
  }
  return headers;
}

This helper is for an API that uses a Bearer token and a JSON request body. Omitting the argument leaves out Authorization. It does not validate the token, obtain one or decide whether the caller is permitted to use the endpoint. Use a synthetic value when experimenting with the example.

Pass the token value without adding a second Bearer prefix. The helper deliberately rejects whitespace-containing values so that a pasted full Authorization line is not quietly accepted as a token. Another authentication mechanism needs a different builder rather than an extra competing Authorization header.

Match Content-Type to the actual bytes

The Content-Type reference describes the representation's media type. A JSON header does not serialize an object: construct the request body with JSON.stringify or the appropriate serializer. Form-encoded and multipart bodies require their own construction rules.

When using FormData in a browser, let the browser generate the multipart boundary instead of copying a bare multipart/form-data header from a tutorial. The boundary in the header and body must agree. The JSON helper above is therefore not suitable for a FormData upload.

Avoid accidental duplicate or inherited values

Use set when the application intends one current value for a header. Repeated append calls can combine values, which is inappropriate for a single credential field. Inspect the final outgoing request after libraries, interceptors or client presets have applied their changes.

Header names are case-insensitive. Authorization and authorization should not be treated as two independent ways to supply different credentials. A browser Headers object normalizes this behavior, while a hand-built object or text parser can make duplicate handling less obvious.

Do not copy Content-Length, Host or connection-management headers from a captured browser request into ordinary application code. The browser controls several transport-level fields. A server-side client has different capabilities, but still needs correct byte accounting and protocol behavior.

Distinguish API requirements from browser permission

Cross-origin requests with certain headers can require a preflight. The server must permit the intended origin, method and header names under its CORS policy. Adding Access-Control-Allow-Origin to the request does not modify that server policy.

The Accept reference explains response-format negotiation. If an endpoint cannot provide an acceptable representation, diagnose that contract mismatch separately from authentication or CORS. Changing Accept does not change the media type of the body you already sent.

Verify the final request and protect its secrets

Test the helper without a token, with one synthetic token and with invalid inputs such as an empty string or a full prefixed header value. Assert that the final request contains one intended credential and that its serialized body matches Content-Type. Keep real credentials out of fixture files and test output.

In the REST API Testing Tool, supply the documented request headers for an endpoint you are authorized to access. If using Bearer authentication, leave the separate Basic-auth field empty so it does not select a different scheme. Compare the actual request and response instead of relying only on a generated preview.