Authentication
Most APIs require some form of authentication. This page covers the most common patterns for attaching credentials to axios requests.
Bearer tokens (JWT)
The most common approach is to attach a JWT in the Authorization header. The cleanest way to do this is via a request interceptor on your axios instance, so the token is read fresh on every request:
import axios from "axios";
const api = axios.create({ baseURL: "https://api.example.com" });
api.interceptors.request.use((config) => {
const token = localStorage.getItem("access_token");
if (token) {
config.headers.set("Authorization", `Bearer ${token}`);
}
return config;
});HTTP Basic auth
For APIs that use HTTP Basic authentication, pass the auth option. axios will encode the credentials and set the Authorization header automatically:
const response = await axios.get("https://api.example.com/data", {
auth: {
username: "myUser",
password: "myPassword",
},
});If auth is not supplied, the Node.js HTTP and fetch adapters can also derive Basic auth credentials from the request URL, for example https://myUser:myPassword@api.example.com/data. Percent-encoded URL credentials are decoded before the Authorization header is generated. Prefer the explicit auth option for new code; it takes precedence over URL-embedded credentials.
UTF-8 usernames
By default, the XHR and fetch adapters keep their existing username handling for compatibility:
- The XHR adapter sends the username as legacy single-byte (Latin-1) characters and the password as UTF-8.
- The fetch adapter sends UTF-8 credentials, but rejects usernames containing characters above U+00FF.
In both adapters, an unsupported username rejects with ERR_BAD_OPTION_VALUE. If your server expects UTF-8 Basic auth usernames, set transitional.encodeBasicAuthUsername: true per request or on an instance:
await axios.get('/account', {
auth: { username: 'π', password: 'secret' },
transitional: { encodeBasicAuthUsername: true },
});A request-level false overrides an instance opt-in, for example for a legacy XHR endpoint that expects Latin-1 username bytes:
const api = axios.create({
transitional: { encodeBasicAuthUsername: true },
});
await api.get('/legacy/account', {
auth: { username: 'café', password: 'secret' },
transitional: { encodeBasicAuthUsername: false },
});Keep the following in mind:
- If you currently convert usernames to UTF-8 byte strings yourself, remove that conversion when you opt in to avoid double encoding.
- Do not enable the option for XHR servers that expect legacy Latin-1 username bytes.
- Setting the option to
falsedoes not make the fetch or Node.js HTTP adapters send Latin-1. - The option does not affect the Node.js HTTP adapter or credentials embedded in a fetch request URL.
- ASCII and empty usernames are encoded the same way either way. Malformed UTF-16 strings still reject with
ERR_BAD_OPTION_VALUE. - axios does not negotiate the charset from a server's authentication challenge or normalize Unicode strings.
TIP
For Bearer tokens and API keys, use a custom Authorization header rather than the auth option — auth is only for HTTP Basic.
API keys
API keys are typically passed as a header or a query parameter, depending on what the API expects:
// As a header
const api = axios.create({
baseURL: "https://api.example.com",
headers: { "X-API-Key": "your-api-key-here" },
});
// As a query parameter
const response = await axios.get("https://api.example.com/data", {
params: { apiKey: "your-api-key-here" },
});Token refresh
When access tokens expire, you need to silently refresh them and retry the failed request. A response interceptor is the right place to implement this:
import axios from "axios";
const api = axios.create({ baseURL: "https://api.example.com" });
// Track whether a refresh is already in progress to avoid parallel refresh calls
let isRefreshing = false;
let failedQueue = [];
const processQueue = (error, token = null) => {
failedQueue.forEach((prom) => {
if (error) {
prom.reject(error);
} else {
prom.resolve(token);
}
});
failedQueue = [];
};
api.interceptors.response.use(
(response) => response,
async (error) => {
const originalRequest = error.config;
if (error.response?.status === 401 && !originalRequest._retry) {
if (isRefreshing) {
// Queue the request until the refresh completes
return new Promise((resolve, reject) => {
failedQueue.push({ resolve, reject });
})
.then((token) => {
originalRequest.headers["Authorization"] = `Bearer ${token}`;
return api(originalRequest);
})
.catch((err) => Promise.reject(err));
}
originalRequest._retry = true;
isRefreshing = true;
try {
const { data } = await axios.post("/auth/refresh", {
refreshToken: localStorage.getItem("refresh_token"),
});
const newToken = data.access_token;
localStorage.setItem("access_token", newToken);
api.defaults.headers.common["Authorization"] = `Bearer ${newToken}`;
processQueue(null, newToken);
return api(originalRequest);
} catch (refreshError) {
processQueue(refreshError, null);
// Redirect to login or emit an event
localStorage.removeItem("access_token");
window.location.href = "/login";
return Promise.reject(refreshError);
} finally {
isRefreshing = false;
}
}
return Promise.reject(error);
}
);Cookie-based authentication
For session-based APIs that rely on cookies, set withCredentials: true to include cookies in cross-origin requests:
const api = axios.create({
baseURL: "https://api.example.com",
withCredentials: true, // send cookies with every request
});WARNING
withCredentials: true requires the server to respond with Access-Control-Allow-Credentials: true and a specific (non-wildcard) Access-Control-Allow-Origin.