@authforge/client

TypeScript SDK for AuthForge — self-hosted identity provider. Wraps every gateway endpoint with auto token refresh, typed errors, and pluggable storage.

Works in Node.js, browsers, and edge runtimes.

Installation

pnpm add @authforge/client
npm install @authforge/client
yarn add @authforge/client

Quick start

import { AuthForgeClient, InMemoryStorage } from '@authforge/client';

const auth = new AuthForgeClient({
  baseUrl: process.env.AUTHFORGE_API_URL!,  // e.g. https://your-api.railway.app
  apiKey: process.env.AUTHFORGE_API_KEY!,   // af_<key> from AuthForge UI
  storage: new InMemoryStorage(),            // default — swap for cookie/localStorage
});

// Register
await auth.register({
  email: '[email protected]',
  password: 'secret',
  firstName: 'Alice',
  lastName: 'Smith',
});

// Login
await auth.login({ email: '[email protected]', password: 'secret' });

// Verify (protected route — auto-refreshes on 401)
const session = await auth.verify();
// → { user: { id, email, firstName, ... }, roles: [...] }

Custom storage

import type { TokenStorage } from '@authforge/client';

const cookieStorage: TokenStorage = {
  getAccessToken: () => readCookie('af_access'),
  getRefreshToken: () => readCookie('af_refresh'),
  setTokens: (a, r) => { writeCookie('af_access', a); writeCookie('af_refresh', r); },
  clearTokens: () => { clearCookie('af_access'); clearCookie('af_refresh'); },
};

const auth = new AuthForgeClient({ baseUrl, apiKey, storage: cookieStorage });

API reference

Auth

| Method | Description | |---|---| | sendVerification(email) | Send email verification code | | register(dto) | Register user + persist tokens | | login({ email, password }) | Email/password login + persist tokens | | socialLogin({ provider, token }) | Google or GitHub token exchange | | sendMagicLink({ email }) | Send passwordless link | | verifyMagicLink(token) | Consume magic link token | | refresh() | Force token refresh (deduped) | | logout() | Revoke refresh token + clear storage | | verify() | Verify access token → user + roles | | forgotPassword({ email }) | Send password reset email | | resetPassword({ token, password }) | Consume reset token |

Users

| Method | Description | |---|---| | getUser(userId) | Get user profile | | updateUser(userId, dto) | Update profile fields | | deleteUser(userId) | Delete user |

Token helpers

| Method | Description | |---|---| | getAccessToken() | Read access token from storage | | getRefreshToken() | Read refresh token from storage | | setTokens(tokens) | Persist tokens manually | | clearTokens() | Clear all stored tokens |

Error handling

import {
  AuthForgeError,
  InvalidCredentialsError,
  UserBannedError,
  TokenExpiredError,
} from '@authforge/client';

try {
  await auth.login({ email, password });
} catch (e) {
  if (e instanceof InvalidCredentialsError) {
    // wrong email or password
  } else if (e instanceof UserBannedError) {
    // account is banned
  } else if (e instanceof AuthForgeError) {
    console.error(e.status, e.message);
  }
}

AuthForge setup

1. Deploy AuthForge (see main repo)
2. Admin UI → New App → copy the API key (shown once)
3. Add AUTHFORGE_API_URL and AUTHFORGE_API_KEY to your app env
4. Done — no auth logic needed in your SaaS

License

MIT © Laurent Schall-Fonteilles