axios-cookie-auth

axios-cookie-auth is a reusable TypeScript utility that simplifies API interactions by providing an Axios instance configured for HTTP-only cookie support. It includes error handling, token refresh logic, CSRF protection, and customizable logout handling.

Installation

To install the package, use npm or yarn:

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

Features

• Simplifies API interaction with preconfigured Axios instance.
• Supports HTTP-only cookies for secure authentication.
• Automatically handles token refresh when encountering 401 Unauthorized errors.
• Supports CSRF protection for modifying requests.
• Allows custom headers and logout logic.

Usage

Import and Setup

import { useApi } from "axios-cookie-auth";

const api = useApi(
  "https://api.example.com", // Base URL for API
  "/auth/refresh", // Endpoint for token refresh
  { "Custom-Header": "value" }, // Optional custom headers
  true, // Enable CSRF protection (optional)
  () => console.log("Logout triggered!") // Optional logout handler
);

// Example API call
api
  .get("/endpoint")
  .then((response) => console.log(response.data))
  .catch((error) => console.error(error));

API

useApi

Parameters

| Name | Type | Required | Description | | ----------------- | ------------------------ | -------- | ------------------------------------------------------------------------------------- | | baseURL | string | Yes | The base URL for all API requests. | | refreshEndpoint | string | Yes | The endpoint used to refresh the authentication token. | | headers | Record<string, string> | No | Optional custom headers to include in each request. | | useCsrf | boolean | No | Whether to include CSRF token protection for modifying requests (default is false). | | logoutFn | () => void | No | Optional callback function to call when token refresh fails. |

Returns

AxiosInstance: A preconfigured Axios instance with interceptors for token refresh, CSRF protection, and error handling.

Example

const api = useApi(
  "https://myapi.com",
  "/refresh",
  { Authorization: "Bearer token" },
  true, // Enable CSRF protection
  () => {
    console.log("User logged out.");
  }
);

api
  .post("/data", { key: "value" })
  .then((response) => console.log(response.data))
  .catch((error) => console.error(error));

Interceptor Behavior

• On success: Passes the response back to the calling function.
• On 401 Unauthorized: Automatically triggers the token refresh endpoint and retries the original request.
• On refresh failure: Calls the optional logoutFn if provided, then rejects the error.

CSRF Protection

• If useCsrf is set to true, the hook will look for a CSRF token stored in localStorage and automatically include it in the request headers as x-xsrf-token.
• This ensures that your API is protected against CSRF attacks when making modifications.

Types

This package is written in TypeScript and provides the following types:

• baseURL: string (Required)
• refreshEndpoint: string (Required)
• headers: Record<string, string> (Optional)
• useCsrf: boolean (Optional, default is false)
• logoutFn: () => void (Optional)

Contribution

Contributions are welcome! Feel free to open issues or submit pull requests.

License

This project is licensed under the MIT License.