axios-auth-client

A lightweight, framework-agnostic Axios wrapper with automatic JWT access token refresh (proactive + reactive), 401 retry logic, and custom refresh support — written in TypeScript.

Features

• Proactive token refresh — Detects when the JWT is about to expire (configurable threshold) and refreshes it before the request is sent
• Reactive 401 handling — Automatically retries failed requests after refreshing the token on a 401 Unauthorized response
• Queue / subscriber pattern — Concurrent requests during a token refresh are queued and replayed once the new token is available — no duplicate refresh calls
• Custom refresh function — Bring your own refresh logic via customRefreshFn for non-standard auth flows
• Flexible token response path — Extract the new access token from any nested field in the refresh endpoint response using dot-notation (e.g. "data.token")
• Configurable token header — Use Authorization, x-access-token, or any custom header
• Public client mode — Skip auth entirely for unauthenticated routes via isPublic: true
• Full TypeScript support — Ships with .d.ts declarations; all Axios types are re-exported
• Zero runtime dependencies — axios is a peer dependency; the package itself has no extra runtime deps
• Universal environment support — Works in browsers (uses atob) and Node.js (manual base64 fallback) without any polyfills

---

Installation

npm install axios-auth-client axios
# or
yarn add axios-auth-client axios

Peer dependency: axios ^1.6.0 is required.

---

Quick Start

import { ApiClient } from "axios-auth-client";

const client = new ApiClient(
  // Axios config (baseURL, timeout, etc.)
  { baseURL: "https://api.example.com" },

  // Auth config
  {
    getAccessToken: () => localStorage.getItem("accessToken"),
    getRefreshToken: () => localStorage.getItem("refreshToken"),
    setAccessToken: (token) => localStorage.setItem("accessToken", token),
    removeTokens: () => {
      localStorage.removeItem("accessToken");
      localStorage.removeItem("refreshToken");
    },
    refreshTokenEndpoint: "/auth/refresh",
    onAuthFailure: () => {
      // e.g. redirect to login
      window.location.href = "/login";
    },
  },
);

// Use like a normal HTTP client
const user = await client.get<User>("/users/me");
const created = await client.post<Post>("/posts", { title: "Hello" });

---

API Reference

new ApiClient(axiosConfig, authConfig, options?)

Parameter	Type	Description
axiosConfig	CreateAxiosDefaults	Standard Axios instance configuration (baseURL, headers, etc.)
authConfig	AuthConfig	Token management callbacks and refresh settings
options	ApiClientOptions	Optional — pass { isPublic: true } to skip auth entirely

---

AuthConfig

Property	Type	Required	Default	Description
getAccessToken	() => string | null	✅	—	Returns the current access token
getRefreshToken	() => string | null	✅	—	Returns the current refresh token
setAccessToken	(token: string) => void	✅	—	Persists the new access token
removeTokens	() => void	✅	—	Clears both tokens (called on auth failure)
refreshTokenEndpoint	string	✅	—	Endpoint path for token refresh (e.g. "/auth/refresh")
onAuthFailure	() => void	❌	undefined	Called after refresh fails — use to redirect to login
tokenHeader	string	❌	"Authorization"	HTTP header used to send the access token
expiryThresholdSeconds	number	❌	60	Seconds before JWT expiry to trigger a proactive refresh
customRefreshFn	(instance: AxiosInstance) => Promise<string>	❌	undefined	Override the default refresh logic with your own
sendRefreshTokenInBody	boolean	❌	false	Send the refresh token in the request body instead of the header
tokenResponsePath	string	❌	"accessToken"	Dot-notation path to the access token in the refresh response (e.g. "data.token")

---

HTTP Methods

All methods are generic and return Promise<T> (unwrapped response.data).

client.get<T>(url, params?, config?)
client.post<T, D>(url, data?, params?, config?)
client.put<T, D>(url, data?, params?, config?)
client.patch<T, D>(url, data?, params?, config?)
client.delete<T>(url, params?, config?)

Utility Methods

// Update default headers on the underlying Axios instance
client.updateDefaultHeaders({ "x-tenant-id": "abc123" });

// Access the raw Axios instance for advanced use cases
const axiosInstance = client.getAxiosInstance();

---

Advanced Usage

Custom Refresh Function

If your API has a non-standard token refresh flow, pass a customRefreshFn:

const client = new ApiClient(
  { baseURL: "https://api.example.com" },
  {
    // ...required callbacks...
    refreshTokenEndpoint: "/auth/refresh", // still required to avoid interceptor loops
    customRefreshFn: async (axiosInstance) => {
      const res = await axiosInstance.post("/auth/custom-refresh", {
        token: mySpecialToken,
      });
      return res.data.jwt; // return the new access token string
    },
  },
);

Nested Token Response Path

If your refresh endpoint returns the token at a nested path:

{ "data": { "tokens": { "access": "eyJ..." } } }

Set tokenResponsePath accordingly:

tokenResponsePath: "data.tokens.access";

Public Client (No Auth)

For routes that don't need authentication:

const publicClient = new ApiClient(
  { baseURL: "https://api.example.com" },
  authConfig,
  { isPublic: true },
);

const posts = await publicClient.get("/public/posts");

Refresh Token Sent in Body

Some APIs expect the refresh token in the POST body:

sendRefreshTokenInBody: true;
// POSTs: { refreshToken: "<token>" }

---

How It Works

Proactive Refresh (Pre-request)

On every outgoing request, the request interceptor decodes the JWT payload and checks the exp claim. If the token expires within expiryThresholdSeconds (default: 60s), a refresh is triggered before the request is dispatched. This prevents unnecessary 401s.

Reactive Refresh (Post-401)

If the server responds with a 401 Unauthorized, the response interceptor catches it (once per request, via an _retry flag), refreshes the token, and replays the original request with the new token.

Concurrent Request Queuing

If multiple requests fire simultaneously while a refresh is already in-progress, they are queued via a subscriber/promise pattern. All queued requests resume automatically once the single refresh resolves — ensuring only one refresh call is ever made at a time.

Request A ──► isRefreshing=true ──► refresh call ──► newToken ──► retry A
Request B ──► queued ────────────────────────────────────────► retry B
Request C ──► queued ────────────────────────────────────────► retry C

---

TypeScript

Full type definitions are included. Commonly used Axios types are re-exported for convenience:

import type {
  AuthConfig,
  ApiClientOptions,
  QueryParams,
  AxiosInstance,
  AxiosRequestConfig,
  AxiosResponse,
  AxiosError,
} from "axios-auth-client";

---

Requirements

• Node.js >= 16
• TypeScript >= 5.x (for consumers using TypeScript)
• axios ^1.6.0 (peer dependency)

---

License

MIT © Usama Imran