Setting Headers in Axios: Per-Request, Global, and Dynamic Patterns
Headers carry credentials, content descriptions, roles, and other request metadata. Axios offers several places to define them, and choosing the right layer prevents repetition while keeping exceptions explicit. This guide covers installation, individual requests, shared defaults, isolated clients, interceptors, precedence, and common failure modes.
Install and import Axios
Install Axios with the package manager used by the project, or load the browser build when no bundler is available. The examples assume Axios v1 and Node.js 20 or later. In ESM projects, import the default export; in older CommonJS projects, require the package; after loading the CDN build in a browser, use the global value. See protected modules code0002 through code0006 for the exact installation and import forms.
Set headers for one request
Use a request-level headers object when only one call needs a value. This approach works for GET requests carrying an API key or preferred response format, POST requests carrying a body and content description, and PUT or DELETE requests carrying an authorization token. Because the values live in that call's configuration, global defaults remain unchanged. See protected modules code0007, code0008, and code0009.
Share headers globally or through an instance
Choose the narrowest shared layer that fits the job. Use axios.defaults.headers.common when every method should inherit a value. Use a method-specific bucket when only POST, PUT, or another method needs it. Use axios.create() when different services need separate base URLs and header sets, reducing the chance that credentials for one service leak into another. See protected modules code0010, code0011, and code0012.
Automate changing values with interceptors
A request interceptor is useful when a value changes over time. It can read a token from browser storage or from memory in Node.js and add an Authorization header before each request. A response interceptor can handle an expired-token response, refresh the credential through a separate client, update the original request, and retry it once. Using a separate refresh client avoids recursive interception. The same mechanism can add role, URL-dependent, or method-dependent headers. See protected modules code0013 through code0017 and code0022.
Understand precedence before debugging
Headers are combined in this order: library defaults, global defaults, instance defaults, and per-request configuration. Request interceptors then run and can replace the merged result. That ordering explains why an interceptor can win even when a request supplied its own value. If per-request values should remain authoritative, the interceptor should fill in a header only when it is absent. See protected modules code0018, code0019, and code0020.
Handle environment, browser, and upload cases
Read secrets from environment variables instead of embedding them in code. Add headers conditionally when the destination URL or HTTP method requires them. Use standard header casing for strict or older backends. For browser sessions, enable credential support and confirm that the server permits credentials from a specific origin rather than a wildcard. For file uploads, let the runtime create the multipart content type and boundary for a real FormData object; in Node.js, use the form library's generated headers. See protected modules code0021, code0024, code0025, code0026, code0027, and code0029 through code0031.
Distinguish browser limits from Node.js behavior
Browsers enforce CORS, restrict some headers, and reject invalid HTTPS certificates before Axios can proceed; there is no client-side switch that disables those platform rules. Node.js has no CORS origin enforcement and permits custom headers and controlled TLS behavior, including an agent that accepts self-signed certificates for development. Treat relaxed TLS settings as development-only because they weaken certificate verification. See protected module code0023.
Decision checklist
Start with the scope: one call, all calls, one method, or one isolated client. Next, identify whether the value is static, environment-based, role-based, or refreshed at runtime. Then check precedence and interceptors before changing server settings. Finally, test the exact browser or Node.js environment in which the request will run, because CORS, cookies, storage, and TLS behavior differ between them.
| Situation | Preferred layer | Why it fits |
|---|---|---|
| One endpoint needs a key or token | Per-request headers | Keeps the exception local and visible. |
| Every request needs the same value | Global defaults | Defines the value once for all methods. |
| Only POST or PUT needs a value | Method-specific defaults | Limits inheritance to that method. |
| Two services need different credentials | Separate axios.create() instances | Prevents shared defaults from crossing service boundaries. |
| Token or role changes at runtime | Request interceptor | Reads the current value immediately before dispatch. |
| Expired token must be refreshed and retried | Response interceptor plus separate refresh client | Handles recovery once without recursive refresh calls. |
Use the narrowest layer that covers the intended requests.
Frequently asked questions
How do I set Axios headers only once?
Define headers once through axios.defaults.headers or through a dedicated instance created with axios.create(). Each later call inherits those values unless its own request configuration replaces them.
Why are my Axios headers not applied?
Check for CORS or browser restrictions on custom headers, inconsistent casing, and interceptors that replace the merged configuration. Confirm the server permits the header and inspect the final request configuration before it is sent.
Can I override global Axios headers?
Yes. A header supplied for an individual request takes precedence over a global default, allowing a different content type, token, or other value for that call while retaining the shared defaults elsewhere.
How do I add Authorization headers dynamically?
Use a request interceptor that obtains the current token from browser storage, memory, or another token store and writes it into the Authorization header immediately before dispatch. This keeps every call using the latest value without editing each request.