JS Web SDK Overview

Introduction

@authrim/web is Authrim’s browser SDK. It provides a simple, unified API for adding authentication to web applications — including Passkey login, Email Code verification, Social Login, session management, and optional OAuth/OIDC flows.

The SDK wraps @authrim/core with browser-specific implementations (Web Crypto API, Fetch API, browser storage) so you can focus on your application rather than protocol details.

This SDK is for Browser Applications

@authrim/web is designed for browser-based login flows — Passkey, Email Code, Social Login, and OAuth/OIDC. It does NOT validate access tokens on the server side or provide server-rendered authentication.

• For SvelteKit apps (SSR + Svelte stores + components), use @authrim/sveltekit instead of this SDK.
• For validating access tokens on your API server, use @authrim/server.
• For building custom platform adapters, use @authrim/core.

What You Can Do

• Passkey: Sign up, sign in, and register additional passkeys using WebAuthn
• Email Code: Send and verify one-time codes via email
• Social Login: Sign in with Google, GitHub, Apple, and other providers via popup or redirect
• Session Management: Check authentication status, get user info, refresh and invalidate sessions
• Authenticated Fetch: Call APIs with DPoP-bound access tokens or same-origin cookie profile requests
• Advanced Account Flows: Handoff SSO verification, step-up, customer profile updates, and device inventory
• OAuth / OIDC (optional): Popup login, redirect flow, silent authentication, and cross-domain SSO

Architecture

@authrim/web sits between your application code and the Authrim server:

flowchart TB
    app["Your Web Application"]
    web["@authrim/web<br>(Browser SDK)"]
    core["@authrim/core<br>(Protocol Layer)"]
    server["Authrim Server"]
    app --> web --> core --> server

• @authrim/web — Browser-specific API. Provides createAuthrim() factory, namespace-based methods, and event system.
• @authrim/core — Platform-agnostic protocol implementation. Handles OAuth 2.0, OIDC, PKCE, DPoP, and token management internally.

You do not need to import or configure @authrim/core directly — @authrim/web handles it for you.

Direct Auth vs OAuth / OIDC

@authrim/web supports two authentication modes:

Mode	Use Case	Configuration
Direct Auth	Passkey, Email Code, Social Login — no OAuth redirect needed	Default (no extra config)
OAuth / OIDC	Standard OAuth flows, popup login, silent auth, cross-domain SSO	enableOAuth: true

Direct Auth is the simplest path. The SDK communicates directly with the Authrim server’s Direct Auth endpoints, handling WebAuthn ceremonies, email code exchange, and social provider popup flows internally.

OAuth / OIDC mode adds the oauth namespace, enabling standard authorization code flow (with PKCE), popup-based login, iframe silent authentication, and cross-domain SSO via top-level navigation.

You can use both modes together — Direct Auth methods are always available regardless of the enableOAuth setting.

Response Pattern

Direct Auth and OAuth methods return an AuthResponse<T> object — a discriminated union of { data, error }:

const { data, error } = await auth.passkey.login();

if (error) {
  // error: { code, error, message, retryable, severity }
  console.error(error.message);
  return;
}

// data is guaranteed to be non-null here
console.log('User:', data.user);
console.log('Session:', data.session);

This pattern applies to passkey, emailCode, social, session, and oauth. Protected-resource helpers such as auth.stepUp, auth.customerProfiles, auth.devices, and auth.fetch() return their API results directly and should be wrapped in try/catch when failures matter.

API Namespaces

The SDK organizes methods into namespaces:

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

// Passkey
auth.passkey.login()
auth.passkey.signUp({ email })
auth.passkey.register()
auth.passkey.isSupported()

// Email Code
auth.emailCode.send(email)
auth.emailCode.verify(email, code)

// Social Login
auth.social.loginWithPopup('google')
auth.social.loginWithRedirect('github')
auth.social.handleCallback()

// Session
auth.session.get()
auth.session.isAuthenticated()
auth.session.refresh()

// Protected resource calls and advanced flows
auth.fetch('/api/me')
auth.handoff.verifyAndSave(handoffToken, state)
auth.stepUp.start({ step_up_token })
auth.customerProfiles.getWithElevationGrant(userId, { accessToken })
auth.customerProfiles.updateDelegated(userId, input, { accessToken, stepUpReceipt })
auth.devices.list()

// Shortcuts
auth.signIn.passkey()
auth.signIn.social('google')
auth.signUp.passkey({ email })
auth.signOut()
auth.signOutApplicationGroup()
auth.signOutAll()

// Events
auth.on('auth:login', (payload) => { ... })
auth.on('auth:logout', (payload) => { ... })
auth.on('token:refreshed', (payload) => { ... })

When enableOAuth: true is set, the oauth namespace is also available:

auth.oauth.popup.login()
auth.oauth.silentAuth.check({ redirectUri })
auth.oauth.trySilentLogin()
auth.oauth.handleSilentCallback()

Browser Support

Browser	Version	Notes
Chrome	67+	Full support including WebAuthn
Firefox	60+	Full support
Safari	14+	Full support (WebAuthn since 14)
Edge	79+	Chromium-based, full support

Note

Passkey features require WebAuthn support. Use auth.passkey.isSupported() to check at runtime.

Next Steps

• Installation & Quick Start — Install the package and create your first login
• Example App — Walk through a complete working example
• Passkey Authentication — WebAuthn-based passwordless login
• Configuration Reference — All available options