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
  tenantId: 'tenant_123',
  enableOAuth: false,
  storage: { ... },
  profile: 'token',
  browserPublicClientMode: 'strict',
  browserRefreshTokenPolicy: 'disabled',
  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

Note

Direct Auth methods (passkey, emailCode, social, session) are always available regardless of enableOAuth.

tenantId

Type	Default	Description
string	—	Tenant id used to scope browser DPoP key material

Set this when your app knows the active tenant before creating the SDK client. It prevents browser-held DPoP keys from being reused across tenants for the same issuer and client id.

storage

Type	Default	Description
StorageOptions	See below	Storage configuration

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

Storage Types

Type	Scope	Persistence	Security
'memory'	Current page lifecycle	Cleared on reload/navigation	Most secure (no DOM storage)
'sessionStorage'	Current tab	Survives reload, cleared on tab close	Accessible to JS in the tab
'localStorage'	All tabs	Persistent across browser restarts	Accessible to JS across tabs

Note

localStorage is accepted by the general browser storage provider, for example for core/OAuth state. Direct Auth access and refresh tokens are only persisted in memory or, when explicitly configured, sessionStorage.

// Default / strict security
storage: { storage: 'memory' }

// Reload persistence
storage: { storage: 'sessionStorage' }

// Persistent general storage; Direct Auth tokens still use memory
// unless sessionStorage is selected.
storage: { storage: 'localStorage', prefix: 'myapp-auth' }

profile

Type	Default	Description
'token' | 'cookie'	'token'	Browser session profile

@authrim/web defaults to the browser-token profile. Use profile: 'cookie' only when your app is integrated with a same-origin token-handler or BFF that owns an HttpOnly cookie session. profile: 'auto' is reserved for framework adapters such as @authrim/sveltekit; do not use it directly with @authrim/web.

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

browserPublicClientMode

Type	Default	Description
'strict' | 'cookie_fallback' | 'legacy'	'strict'	Browser public-client security mode

Custom browser SDK clients default to strict. Hosted or BFF-style integrations may select cookie_fallback at the integration boundary.

browserRefreshTokenPolicy

Type	Default	Description
'disabled' | 'dpop_bound'	'disabled'	Browser refresh token policy

Use dpop_bound only when the browser can keep stable non-extractable DPoP key material for this issuer and client.

csrf

Type	Default	Description
{ cookieName?: string; headerName?: string }	{ cookieName: 'authrim_csrf', headerName: 'X-Authrim-CSRF' }	Double-submit CSRF integration for cookie profile requests

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.handoff	Verify Smart Handoff SSO tokens
auth.stepUp	Start, resend, and complete step-up challenges
auth.customerProfiles	Delegated/elevated customer profile reads and writes
auth.devices	List, rename, and unlink trusted devices
auth.fetch()	Fetch protected resources with token or cookie profile behavior
auth.signIn	Sign-in shortcuts
auth.signUp	Sign-up shortcuts
auth.signOut()	Sign out
auth.signOutApplicationGroup()	Sign out the current application group
auth.signOutAll()	Global 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,
  tenantId: 'tenant_123',
  storage: {
    prefix: 'myapp',
    storage: 'sessionStorage',
  },
  profile: 'token',
  browserPublicClientMode: 'strict',
  browserRefreshTokenPolicy: 'disabled',
  csrf: {
    cookieName: 'authrim_csrf',
    headerName: 'X-Authrim-CSRF',
  },
  silentLoginRedirectUri: 'https://myapp.com/callback',
});

Next Steps

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