Axios Set Headers in 2026: The Developer Playbook

Before any pattern below behaves the way the docs claim, pin your version. This article targets Axios v1.x on Node 20 or later. The 0.x line normalized headers differently, so v1 patterns will not all translate cleanly.

Install through any package manager:

npm install axios
# or: yarn add axios   |   pnpm add axios

ESM project:

import axios from "axios";

CommonJS service:

const axios = require("axios");

Plain browser page:

<script src="https://cdn.jsdelivr.net/npm/axios@1/dist/axios.min.js"></script>

One environmental detail that comes back later: in Node, Axios uses the built-in http/https stack, so you control TLS, agents, and proxies. In the browser, it uses XMLHttpRequest, so the browser enforces CORS and SameSite rules regardless of what you configure. If you also need a proxy layer, a dedicated Axios proxy walkthrough covers that wiring end to end.

Per-request headers are the most direct way to Axios set headers for a single call. They are the right default for one-off auth, content negotiation, and isolated debugging. Nothing is shared across calls, nothing leaks into other modules, and a header set this way wins against every default layer below it.

// GET with auth and a custom Accept
const orders = await axios.get("https://api.example.com/orders", {
  headers: {
    Authorization: `Bearer ${token}`,
    Accept: "application/vnd.example.v2+json",
  },
});

// POST: body in arg 2, config in arg 3
const created = await axios.post(
  "https://api.example.com/orders",
  { sku: "ABC-123", quantity: 2 },
  { headers: { "Idempotency-Key": crypto.randomUUID() } }
);

// PUT and PATCH follow the same three-argument shape as POST
await axios.put(url, body, { headers: { "If-Match": etag } });
await axios.patch(url, body, {
  headers: { "Content-Type": "application/merge-patch+json" },
});

// DELETE takes config in arg 2, like GET
await axios.delete(url, {
  headers: { Authorization: `Bearer ${token}` },
});

A few rules worth internalizing. The headers object accepts string values only in v1; arrays and null are not the supported shape. Anything you set per request is the final word, even if a request interceptor tries to overwrite it later (the guard pattern is shown below). And this Axios headers example is the cleanest way to make one specific call ignore everything global, since per-request keys beat every other layer.

The most common Axios bug filed by beginners is not a header bug at all, it is an argument-slot bug. axios.get and axios.delete accept config as the second argument because they have no body. axios.post, axios.put, and axios.patch accept config as the third argument because the body lives in arg two.

Get this wrong and your headers end up inside the body. The server sees no Authorization, returns 401, and you spend an hour blaming your token store.

// WRONG: headers object treated as the POST body
await axios.post("https://api.example.com/orders", {
  headers: { Authorization: `Bearer ${token}` }, // becomes the request body
});

// RIGHT: empty body, headers in the third slot
await axios.post(
  "https://api.example.com/orders",
  {},                                                // body
  { headers: { Authorization: `Bearer ${token}` } }  // config
);

The fastest way to confirm a 401 is this misplacement is to log error.config.data and check whether your headers leaked into the body. If they did, move them one slot right. This is the canonical Axios headers POST mistake, and it disappears once you internalize the slot rules.

Axios global headers are set on axios.defaults.headers and apply to every call made through the default instance. They are the right tool for a narrow set of cases: a script that talks to exactly one API, an internal dev tool, a CLI, or a small app that ships its own API client. The moment you call more than one host, defaults become a liability.

// Apply to every method
axios.defaults.headers.common["Accept"] = "application/json";
axios.defaults.headers.common["X-App-Version"] = "2026.04.1";

// Pull secrets from env, never inline
axios.defaults.baseURL = process.env.API_URL;
axios.defaults.headers.common["Authorization"] =
  `Bearer ${process.env.API_TOKEN}`;

The common bucket is the one you usually want, because it applies regardless of HTTP method. Anything you set there shows up on every outbound GET, POST, PUT, PATCH, DELETE, and OPTIONS call from the default Axios singleton.

The maintenance cost shows up later. As soon as a second service or third-party SDK lives in the same codebase, your global Authorization header travels to hosts it has no business touching. The instances section below is where that problem gets fixed properly.

Axios also exposes method-scoped buckets like axios.defaults.headers.post, .get, .put, .patch, and .delete. These only apply to that specific verb, which is occasionally useful when you want a different default per method.

// Force a JSON content type only on writes
axios.defaults.headers.post["Content-Type"] = "application/json";
axios.defaults.headers.put["Content-Type"] = "application/json";
axios.defaults.headers.patch["Content-Type"] = "application/json";

For everything else, reach for common first, then narrow to a method bucket only when you have a real reason. In practice, the method buckets are reference-only knowledge for most teams. Instances are almost always the cleaner shape, and the next section is where Axios default headers stop being your primary tool.

axios.create() is the 2026 default recommendation. You build a small client per upstream service, set its own baseURL and headers, and ship that client to the modules that need it. Each instance is independent, so updating one does not bleed into another.

// Internal API: short tokens, custom version header
export const internalApi = axios.create({
  baseURL: "https://internal.example.com/api",
  headers: {
    "Accept": "application/json",
    "X-Internal-Client": "checkout-svc",
  },
});

// Third-party API: completely separate auth and content negotiation
export const partnerApi = axios.create({
  baseURL: "https://partner.example.com",
  headers: {
    "Accept": "application/vnd.partner.v3+json",
    "X-Partner-Key": process.env.PARTNER_KEY,
  },
});

You set headers per instance the same way you set globals, just on the instance object:

// After login, write the new token to one instance only
internalApi.defaults.headers.common["Authorization"] = `Bearer ${jwt}`;

Two things this pattern buys you. Your Authorization header only ever flies to the host that issued the token. And when you swap one upstream for another, you change one client file and nothing else. The axios.create headers idiom is what scales without footguns.

When you set axios.defaults.headers.common.Authorization = "Bearer ...", every call that goes through the default Axios singleton sends that token, including third-party SDKs and ad-hoc scripts that import the bare axios module. That includes hosts that have no idea what your JWT is and may log it.

The Axios authorization header should always be scoped to the host that issued it. Two reliable patterns:

// 1. Use a dedicated instance and never touch axios.defaults
internalApi.defaults.headers.common.Authorization = `Bearer ${jwt}`;

// 2. Or guard a request interceptor by baseURL / hostname
axios.interceptors.request.use((cfg) => {
  const host = new URL(cfg.baseURL || cfg.url, "http://x").hostname;
  if (host === "internal.example.com") {
    cfg.headers.Authorization = `Bearer ${jwt}`;
  }
  return cfg;
});

The interceptor pattern is fine for monorepos that share one axios. The instance pattern is cleaner everywhere else.

A request interceptor is the Axios set headers tool you reach for when the header has to be computed at call time, not at module load. It runs on every outbound request before it leaves Axios. It is where the Axios request interceptor pattern earns its place: read the current token from wherever it lives, attach it to config.headers, return the modified config.

Two storage flavors cover most apps. In the browser you usually read from localStorage, sessionStorage, or memory. In Node you keep a small token store module that the rest of the app talks to.

// Browser: read the latest token on every request
internalApi.interceptors.request.use((config) => {
  const token = localStorage.getItem("access_token");
  if (token) {
    config.headers.Authorization = `Bearer ${token}`;
  }
  return config;
});

// Node: module-level store, swap-able for Redis or a vault
import { getToken } from "./auth/token-store.js";

internalApi.interceptors.request.use(async (config) => {
  const token = await getToken();
  if (token && !config.headers.Authorization) {
    config.headers.Authorization = `Bearer ${token}`;
  }
  return config;
});

That if (!config.headers.Authorization) guard matters. It is also the pattern that lets a per-request override win against the interceptor when you need it, which the merge-order section covers in detail.

Interceptors also handle conditional logic the per-request and defaults layers cannot express cleanly. Role-based headers, environment switches, and URL-aware behavior all belong here:

internalApi.interceptors.request.use((config) => {
  const user = getCurrentUser();
  if (user?.role === "admin") {
    config.headers["X-Admin"] = "true";
  }
  if (config.url?.startsWith("/billing/")) {
    config.headers["X-Sensitive-Path"] = "1";
  }
  if (process.env.NODE_ENV === "development") {
    config.headers["X-Debug-Trace"] = crypto.randomUUID();
  }
  return config;
});

Keep one interceptor per concern when you can. Mixing auth, role flags, and observability into a single function makes debugging painful, and each registered interceptor only runs in registration order anyway.

Token refresh is where most Axios codebases pick up subtle bugs: infinite retry loops, race conditions across parallel requests, and refresh calls that get rewritten by the very interceptor that is supposed to refresh them. The pattern below avoids all three.

The shape is a response interceptor that catches a 401, calls a refresh endpoint with a separate Axios client, marks the original config so it cannot retry forever, retries once, and surrenders to logout on failure.

import axios from "axios";

// 1. Plain client for refresh, with NO interceptors of its own.
//    This is what keeps the refresh call out of the retry loop.
const authClient = axios.create({ baseURL: "https://auth.example.com" });

// 2. Your normal API client with auth wiring.
const api = axios.create({ baseURL: "https://api.example.com" });

api.interceptors.request.use((cfg) => {
  const t = tokenStore.access;
  if (t) cfg.headers.Authorization = `Bearer ${t}`;
  return cfg;
});

api.interceptors.response.use(
  (res) => res,
  async (error) => {
    const original = error.config;
    if (
      error.response?.status !== 401 ||
      original._retry ||
      !tokenStore.refresh
    ) {
      // Either not an auth failure, already retried once,
      // or we have nothing to refresh with.
      return Promise.reject(error);
    }
    original._retry = true; // 3. one shot only, no loops
    try {
      const { data } = await authClient.post("/refresh", {
        refresh_token: tokenStore.refresh,
      });
      tokenStore.access = data.access;
      tokenStore.refresh = data.refresh;
      // 4. write the new token onto the original request and replay it
      original.headers.Authorization = `Bearer ${data.access}`;
      return api(original);
    } catch (refreshErr) {
      tokenStore.clear();
      window.location.href = "/login"; // or your auth flow
      return Promise.reject(refreshErr);
    }
  }
);

A few production notes before this hits real traffic. Share the token store between tabs (a BroadcastChannel listener works in browsers) so a refresh in one tab does not strand another. Wrap the in-flight refresh in a Promise singleton so ten parallel 401s trigger one refresh, not ten. And cap retries beyond _retry if the refresh endpoint can itself return 401, otherwise you loop on a revoked session.

Most Axios set headers guides stop at the request side and never look at what comes back. That is a mistake. The Axios response headers object is where the API tells you how to behave next: how many requests you have left, whether your cached copy is still good, and where the next page lives. Skip it, and your scraper looks polite on day one and gets throttled by day three.

Axios exposes response headers on response.headers. The keys are lowercased, regardless of how the server cased them on the wire. That is the single most common surprise when you start reading them. The MDN HTTP Conditional Requests guide covers the spec for ETag and If-None-Match.

const res = await api.get("/orders");

// All read as lowercase keys, regardless of server casing
const limit = Number(res.headers["x-ratelimit-limit"]);
const remaining = Number(res.headers["x-ratelimit-remaining"]);
const resetAt = new Date(Number(res.headers["x-ratelimit-reset"]) * 1000);

console.log(`API budget: ${remaining}/${limit}, resets at ${resetAt.toISOString()}`);

For cache-friendly polling, store the ETag and replay it via If-None-Match. If the resource has not changed, the server returns 304 with an empty body and your code skips the parse:

let cachedEtag = null;
let cachedBody = null;

async function pollOrders() {
  try {
    const res = await api.get("/orders", {
      headers: cachedEtag ? { "If-None-Match": cachedEtag } : {},
      validateStatus: (s) => s === 200 || s === 304, // 304 is not an error
    });
    if (res.status === 200) {
      cachedEtag = res.headers["etag"];
      cachedBody = res.data;
    }
    return cachedBody;
  } catch (err) {
    /* network/HTTP errors only land here now */
  }
}

Paginated APIs frequently use the Link header (RFC 8288) with rel="next" and rel="prev". Walk it manually or use a parser:

function nextLink(linkHeader) {
  if (!linkHeader) return null;
  const match = linkHeader.split(",").find((p) => /rel="next"/.test(p));
  return match ? match.match(/<([^>]+)>/)[1] : null;
}

let url = "/orders?per_page=100";
while (url) {
  const res = await api.get(url);
  process(res.data);
  url = nextLink(res.headers["link"]);
}

Headers worth monitoring on most APIs:

If your code only inspects response.data, you are throwing away half of what the API is trying to tell you.

Every time you Axios set headers from more than one layer, the library has to merge them. Headers are computed at request time by walking five layers and applying them last-write-wins. Knowing the order is what lets you predict which header your server actually sees.

The merge order, from lowest priority to highest:

1. Library defaults. Built-in Axios values like Accept: application/json, text/plain, */* and the method-aware Content-Type for write requests.
2. Global defaults. Anything you put on axios.defaults.headers.common, .post, .get, and friends.
3. Instance defaults. Headers set on a client created with axios.create({ headers: ... }) or assigned to instance.defaults.headers.* afterward.
4. Per-request config. The headers object you pass directly to axios.get(url, { headers }), axios.post(url, body, { headers }), and so on.
5. Request interceptors. Anything an interceptor writes to config.headers before the request leaves Axios. These run after the per-request merge.

Because interceptors run last, they technically beat per-request headers. That trips up almost everyone the first time. The fix is a guard inside the interceptor that respects an existing value:

api.interceptors.request.use((config) => {
  // Only inject if the caller has not already set Authorization
  if (!config.headers.Authorization) {
    const t = tokenStore.access;
    if (t) config.headers.Authorization = `Bearer ${t}`;
  }
  return config;
});

With that guard in place, a per-request Authorization survives the interceptor stack and your override behaves intuitively. This is the same pattern that lets one specific call use a service-to-service token while the rest of the app uses a user token.

Most production header issues collapse into four patterns: a stripped multipart boundary on uploads, a CORS or withCredentials mismatch in the browser, a self-signed TLS cert in Node, and case-sensitive backends that reject the wire format Axios sends. The four subsections below are written so you can land on any one of them directly from search and apply the fix without scrolling back.

The single most common Axios FormData Content-Type bug is the "fix" people apply on instinct: setting Content-Type: multipart/form-data themselves. That value alone is incomplete, because real multipart bodies require a boundary parameter the server uses to separate fields. When you hardcode the bare value, Axios will not overwrite it, the actual boundary never reaches the wire, and the server rejects the upload.

The right move is to let the runtime build the header for you.

// Node: form-data library exposes getHeaders() with the boundary baked in
import FormData from "form-data";
import fs from "node:fs";

const form = new FormData();
form.append("file", fs.createReadStream("./invoice.pdf"));
form.append("note", "Q4 invoice");

await api.post("/uploads", form, {
  headers: form.getHeaders(), // multipart/form-data; boundary=...
});

// Browser: send a real FormData and let Axios omit Content-Type
const fd = new FormData();
fd.append("file", fileInput.files[0]);
fd.append("note", "Q4 invoice");

await api.post("/uploads", fd); // do not set Content-Type

One exception: if you pass Axios a plain object and let it serialize to FormData internally, an explicit Content-Type: multipart/form-data is fine because Axios will fill in the boundary itself.

CORS is browser-only. Node has no CORS, no blocked headers, and no preflight, so this entire section is something you only debug in a browser tab. Axios CORS headers cannot be disabled from the client; the browser owns the rule and Axios is downstream of it. The canonical reference for what the browser enforces is the MDN CORS guide.

For cross-origin cookies to travel, four things must line up:

1. The client sets Axios withCredentials cookies on. Either instance.defaults.withCredentials = true, or { withCredentials: true } per request.
2. The server returns Access-Control-Allow-Credentials: true.
3. Access-Control-Allow-Origin is a specific origin, never *. The wildcard is rejected once credentials are in play.
4. Cookies are issued with SameSite=None; Secure. A SameSite=Strict cookie will never be sent cross-site, even with withCredentials set.

const api = axios.create({
  baseURL: "https://api.example.com",
  withCredentials: true, // tells the BROWSER to attach cookies
});

If you do not own the upstream API and cannot fix the CORS response, the only honest fix is a small server-side proxy on your own domain that forwards the call. Putting that behind your own subdomain also sidesteps the third-party-cookie deprecation story. A primer on the underlying cookie behavior is worth keeping bookmarked.

In Node, you have full control over TLS, so you can talk to a dev API that uses a self-signed certificate without yelling at the runtime. In a browser, you cannot, and you should not try; the user must trust the CA in the OS or browser store.

For Node-side dev or staging only, attach a custom HTTPS agent. The Node.js https.Agent docs cover every option:

import https from "node:https";

const devApi = axios.create({
  baseURL: "https://dev.internal.local",
  httpsAgent: new https.Agent({ rejectUnauthorized: false }),
});

That flag disables certificate verification, which means man-in-the-middle attacks are no longer detectable. Never ship this to production. The production fix is to put your CA into the system trust store, or to issue a real certificate (Let's Encrypt, an internal ACME server, or your cloud provider's certificate manager). rejectUnauthorized: false is a screwdriver for the dev loop, not a deployment strategy.

HTTP is case-insensitive on paper, but a non-trivial number of legacy backends will refuse a request whose header names are not in canonical mixed case. Axios normalizes some header names internally, but for custom headers you should send the casing the upstream expects.

// Safer than x-api-key on older middleware
await api.get("/secret", {
  headers: { "X-API-Key": process.env.API_KEY },
});

The flip side: when you read those same headers back from response.headers, Axios lowercases every key. So you send X-API-Key but read res.headers["x-api-key"]. This asymmetry is intentional and consistent across v1. Pick canonical casing for outbound, accept lowercase for inbound, and you will never debug a "missing header" again.

Web servers inspect request headers to decide whether the client is a real browser or a bot, and a default Node user agent like axios/1.7.7 is the fastest way to be flagged. If you are using Axios for scraping, ship a believable header bundle and rotate it.

const UA_POOL = [
  "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36",
  "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.2 Safari/605.1.15",
  "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36",
];

const scraper = axios.create({
  headers: {
    "Accept": "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8",
    "Accept-Language": "en-US,en;q=0.9",
    "Accept-Encoding": "gzip, deflate, br",
    "Upgrade-Insecure-Requests": "1",
  },
  timeout: 15_000,
});

// Axios User-Agent rotation per request
scraper.interceptors.request.use((cfg) => {
  cfg.headers["User-Agent"] = UA_POOL[Math.floor(Math.random() * UA_POOL.length)];
  return cfg;
});

This gets you past naive bot filters. Sophisticated targets layer JA3 fingerprints, TLS profiles, Cloudflare challenges, and behavioral checks on top, and no header bundle alone clears those. When axios plus rotation stops being enough, escalate to a residential proxy pool or a managed scraping API that handles fingerprinting, retries, and CAPTCHA workflows for you. A breakdown of why scrapers get blocked beyond headers is a useful next read.

The whole Axios set headers model collapses into a five-layer mental picture, plus one ordering rule:

• Per-request config for one-offs and overrides; wins against every default below.
• Global defaults for single-API scripts and dev tools only; risky once you call multiple hosts.
• axios.create() instances as the 2026 default for any app talking to more than one upstream.
• Request interceptors for cross-cutting concerns like auth injection, role flags, and tracing.
• Response inspection so response.headers actually influences your retry, cache, and pagination logic.

Merge order, low to high: library defaults, global defaults, instance defaults, per-request config, request interceptors. Use the if (!config.headers.x) guard inside interceptors when you want per-request to keep its win.

common applies to every HTTP method on the default Axios instance, so headers set there ride along on GET, POST, PUT, PATCH, and DELETE. post (and .get, .put, .patch, .delete) applies only when that specific verb is used. Reach for common first; use the method buckets only when one verb genuinely needs a different default.

Guard the interceptor so it only writes a header when the caller has not already set one. The pattern is if (!config.headers.Authorization) { config.headers.Authorization = ... }. Because interceptors run after the per-request merge, an unconditional assignment will clobber your override. The guarded version respects whatever the caller passed in.

Axios normalizes response header keys to lowercase by convention. HTTP itself treats header names as case-insensitive, and lowercasing on the read path means you never have to guess casing for etag, content-type, or x-ratelimit-remaining. Send canonical casing on the way out, read lowercase on the way in.

No. CORS is enforced by the browser before Axios ever runs, so there is no client-side flag that disables it. The only real fixes are getting the upstream to send the right Access-Control-Allow-Origin and Access-Control-Allow-Credentials headers, or routing the call through a small server-side proxy you control. Node has no CORS rules at all.

Create a dedicated axios.create() instance for that API and set its Authorization only on the instance. Never write the token to axios.defaults, which broadcasts it to every host the default singleton calls. If you must use one shared instance, guard a request interceptor with a hostname check so the header only attaches when the URL matches your trusted baseURL.

If you internalize one thing from this Axios set headers walkthrough, make it the layering: every header sits in one of five places, and the order is library defaults, global defaults, instance defaults, per-request config, then request interceptors. Pick the highest layer that matches the lifetime of the header. One-shot overrides go per-request. App-wide concerns go on an instance. Cross-cutting auth goes in an interceptor. And every Axios response carries headers that should be influencing your next decision, not getting thrown away.

The same patterns translate when you are doing more than calling well-behaved REST APIs. The moment you point Axios at a target that fingerprints clients, rate-limits aggressively, or hides data behind JavaScript challenges, header rotation alone stops being enough. That is where a managed layer becomes the higher-leverage move: the WebScrapingAPI Scraper API handles proxy rotation, browser-grade TLS fingerprints, and CAPTCHA solving behind a single endpoint, so the Axios code you just wrote keeps its shape and you stop firefighting blocks. Bookmark this as your Axios set headers reference, and reach for the managed path when the request layer is no longer the interesting problem.