Getting started (TypeScript)

@arrow-labs/auth-sdk is the TypeScript client for the platform. The core works in the browser and in Node; framework and runtime helpers ship as subpath exports.

Import	Use
@arrow-labs/auth-sdk	Core API client (sign-in, MFA, profile, sessions, branding)
@arrow-labs/auth-sdk/react	<AuthProvider> + hooks
@arrow-labs/auth-sdk/server	JWT validation + OAuth exchange (Node)
@arrow-labs/auth-sdk/events	RabbitMQ event consumer (Node)

Install

pnpm add @arrow-labs/auth-sdk
# or: npm install @arrow-labs/auth-sdk

Ships dual ESM + CommonJS with bundled types. The core has no peer dependencies.

Configure the API base URL

By default the SDK issues relative requests (suitable when your app is served from the same origin as the API). For any other setup, point it at your API origin once at startup:

import { configureClient } from '@arrow-labs/auth-sdk';

configureClient({ baseUrl: 'https://api.arrowlabs.co.uk' });

Sign in

Every call returns a discriminated result ({ kind: '...' }) — no thrown errors for expected outcomes, so you handle each case explicitly.

import { signIn } from '@arrow-labs/auth-sdk';

const result = await signIn('acme', { Email: 'user@acme.com', Password: 's3cret' });

switch (result.kind) {
  case 'success':
    console.log('signed in as', result.userId);
    break;
  case 'mfa_required':
    // prompt for a TOTP code, then call the MFA challenge endpoint with result.challengeToken
    break;
  case 'invalid_credentials':
  case 'account_suspended':
  case 'email_unverified':
  case 'rate_limited':
    // show the appropriate message
    break;
  case 'network_error':
    // retry / offline UI
    break;
}

Fetch org branding (unauthenticated)

import { getBranding } from '@arrow-labs/auth-sdk';

const branding = await getBranding('acme');
if (branding.kind === 'success') {
  console.log(branding.branding.display_name);
}

Sessions & credentials

The platform uses an opaque, HttpOnly session cookie. The SDK sends credentials: 'include' on every request:

• Same-origin (behind the shared proxy): works out of the box.
• Cross-origin: the API must allow your origin via CORS with Access-Control-Allow-Credentials: true. External backends typically integrate via the OAuth flow + the server helpers rather than the cookie session directly.

Next steps

• Building a React app? → React
• Protecting a Node API or running OAuth server-side? → Server
• Consuming platform events? → Events