Configuration Reference

createAuthrim Options

The createAuthrim() function accepts an AuthrimConfig object:

import { createAuthrim } from '@authrim/web';

const auth = await createAuthrim({
  // Required
  issuer: 'https://auth.example.com',
  clientId: 'my-app',

  // Optional
  enableOAuth: false,
  storage: { ... },
  silentLoginRedirectUri: 'https://myapp.com/callback.html',
});

Required Options

issuer

Type	Required	Description
`string`	Yes	Authrim IdP URL

The base URL of your Authrim server. The SDK appends well-known paths for discovery, token endpoints, and Direct Auth endpoints.

issuer: 'https://auth.example.com'

clientId

Type	Required	Description
`string`	Yes	OAuth client ID

The client ID registered in the Authrim Admin panel.

clientId: 'my-application'

Optional Options

enableOAuth

Type	Default	Description
`boolean`	`false`	Enable OAuth/OIDC features

When true, the auth.oauth namespace becomes available, providing:

auth.oauth.popup.login() — Popup-based OAuth login
auth.oauth.silentAuth.check() — Iframe-based silent authentication
auth.oauth.trySilentLogin() — Top-level navigation SSO
auth.oauth.handleSilentCallback() — SSO callback handler
auth.oauth.buildAuthorizationUrl() — Manual authorization URL building
auth.oauth.handleCallback() — Manual callback handling

// Without OAuth (default)
const auth = await createAuthrim({
  issuer: 'https://auth.example.com',
  clientId: 'my-app',
});
// auth.oauth is undefined

// With OAuth
const authWithOAuth = await createAuthrim({
  issuer: 'https://auth.example.com',
  clientId: 'my-app',
  enableOAuth: true,
});
// authWithOAuth.oauth is available

storage

Type	Default	Description
`StorageOptions`	See below	Storage configuration

interface StorageOptions {
  /** Key prefix for stored items (default: 'authrim') */
  prefix?: string;
  /** Storage backend (default: 'sessionStorage') */
  storage?: 'memory' | 'sessionStorage' | 'localStorage';
}

Storage Types

Type	Scope	Persistence	Security
`'memory'`	Current tab	Cleared on tab close / navigation	Most secure (no DOM access)
`'sessionStorage'`	Current tab	Survives reload, cleared on tab close	XSS-resistant (tab-scoped)
`'localStorage'`	All tabs	Persistent across browser restarts	Accessible via XSS

// Strict security (SPA)
storage: { storage: 'memory' }

// Default (recommended for most apps)
storage: { storage: 'sessionStorage' }

// Persistent (remember me)
storage: { storage: 'localStorage', prefix: 'myapp-auth' }

silentLoginRedirectUri

Type	Default	Description
`string`	`${window.location.origin}/callback.html`	Redirect URI for silent SSO

Used by auth.oauth.trySilentLogin() and auth.oauth.handleSilentCallback(). Must be a page that calls handleSilentCallback().

silentLoginRedirectUri: 'https://myapp.com/auth/callback'

TypeScript: Conditional Types

The Authrim return type is conditional based on enableOAuth:

// enableOAuth: false (or omitted)
// Type: AuthrimBase
const auth = await createAuthrim({
  issuer: '...',
  clientId: '...',
});
auth.passkey    // ✅ Available
auth.emailCode  // ✅ Available
auth.social     // ✅ Available
auth.session    // ✅ Available
auth.oauth      // ❌ undefined

// enableOAuth: true
// Type: AuthrimWithOAuth
const auth = await createAuthrim({
  issuer: '...',
  clientId: '...',
  enableOAuth: true,
});
auth.passkey    // ✅ Available
auth.oauth      // ✅ Available

API Namespaces

Base (Always Available)

Namespace	Description
`auth.passkey`	Passkey (WebAuthn) authentication
`auth.emailCode`	Email code (OTP) authentication
`auth.social`	Social provider authentication
`auth.session`	Session management
`auth.signIn`	Sign-in shortcuts
`auth.signUp`	Sign-up shortcuts
`auth.signOut()`	Sign out
`auth.on()`	Event subscription

OAuth (enableOAuth: true)

Namespace	Description
`auth.oauth.popup`	Popup-based OAuth login
`auth.oauth.silentAuth`	Iframe-based silent authentication
`auth.oauth.trySilentLogin()`	Top-level navigation SSO
`auth.oauth.handleSilentCallback()`	SSO callback handler
`auth.oauth.buildAuthorizationUrl()`	Manual authorization URL
`auth.oauth.handleCallback()`	Manual callback handling

Shortcuts

The SDK provides shortcut methods for common operations:

// Shortcut: auth.signIn.passkey()
// Equivalent: auth.passkey.login()
const { data, error } = await auth.signIn.passkey();

// Shortcut: auth.signIn.social('google')
// Equivalent: auth.social.loginWithPopup('google')
const { data, error } = await auth.signIn.social('google');

// Shortcut: auth.signUp.passkey({ email })
// Equivalent: auth.passkey.signUp({ email })
const { data, error } = await auth.signUp.passkey({ email: '[email protected]' });

Minimal Configuration

const auth = await createAuthrim({
  issuer: 'https://auth.example.com',
  clientId: 'my-app',
});

Full Configuration

const auth = await createAuthrim({
  issuer: 'https://auth.example.com',
  clientId: 'my-app',
  enableOAuth: true,
  storage: {
    prefix: 'myapp',
    storage: 'sessionStorage',
  },
  silentLoginRedirectUri: 'https://myapp.com/callback',
});

Next Steps

Installation & Quick Start — Getting started
Error Handling — Error codes and patterns
Events — Event system reference