Use this helper when one backend service needs to call another backend service authenticated against Faable Auth. It implements the OAuth2 client-credentials flow and caches the access token until it expires, so most requests skip the token endpoint.

Install

npm install @faable/auth-helpers-axios axios

Peer dependency: axios ^1.7.2.

Usage

Quick start (via environment variables)

Set the three Faable Auth env variables and call authorize() to get a ready-to-use Axios instance:

import { authorize } from "@faable/auth-helpers-axios";

// Reads FAABLEAUTH_DOMAIN, FAABLEAUTH_CLIENT_ID and FAABLEAUTH_CLIENT_SECRET
const api = authorize();

const { data } = await api.get("/me");

Explicit configuration

import { authorize } from "@faable/auth-helpers-axios";

const api = authorize({
  client_credentials: {
    domain: "https://<team>.auth.faable.com",
    clientId: "your-client-id",
    clientSecret: "your-client-secret",
  },
});

Decorating an existing Axios instance

If you already have a configured Axios client (custom baseURL, retries, etc.), pass it in and the helper will attach the auth interceptor to it instead of creating a new one:

import axios from "axios";
import { authorize } from "@faable/auth-helpers-axios";

const client = axios.create({ baseURL: "https://api.faable.com" });

authorize({ client });

// `client` now sends bearer tokens automatically

Environment variables

| Variable | Description | | -------------------------- | ------------------------------------------------- | | FAABLEAUTH_DOMAIN | Faable Auth tenant URL (token endpoint host). | | FAABLEAUTH_CLIENT_ID | App Client ID. | | FAABLEAUTH_CLIENT_SECRET | App Client Secret. |

If FAABLEAUTH_DOMAIN is missing, authorize() throws. If the client id/secret are missing, the helper logs a warning and returns the Axios instance without an authorization interceptor — useful for local development.

API

authorize(config?)

Returns an AxiosInstance that adds Authorization: Bearer <token> to every request, refreshing the token automatically when expired.

| Field | Type | Description | | ------------------------------ | --------------- | ------------------------------------------------------------------------ | | config.client | AxiosInstance | Reuse an existing Axios instance instead of creating one. | | config.client_credentials | object | Inline credentials. Each field falls back to its FAABLEAUTH_* env var. | | config.client_credentials.domain | string | Faable Auth tenant URL. | | config.client_credentials.clientId | string | OAuth client ID. | | config.client_credentials.clientSecret | string | OAuth client secret. |

License

MIT