Skip to content
Authrim

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.

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
  • 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
(Browser SDK)"]
    core["@authrim/core
(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:

ModeUse CaseConfiguration
Direct AuthPasskey, Email Code, Social Login — no OAuth redirect neededDefault (no extra config)
OAuth / OIDCStandard OAuth flows, popup login, silent auth, cross-domain SSOenableOAuth: 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

All async 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 consistently across all SDK methods (passkey, emailCode, social, session, oauth), so error handling follows the same structure everywhere.

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()


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


// Events
auth.on('auth:login', (payload) => { ... })
auth.on('session:expired', (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

BrowserVersionNotes
Chrome67+Full support including WebAuthn
Firefox60+Full support
Safari14+Full support (WebAuthn since 14)
Edge79+Chromium-based, full support

Next Steps