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)

Contributing

See CONTRIBUTING.md for development guidelines.

License

This project is licensed under the MIT License.