Installation & Quick Start

Installation

npm / pnpm / yarn

# npm
npm install @authrim/web

# pnpm
pnpm add @authrim/web

# yarn
yarn add @authrim/web

Then import in your application:

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

CDN (Script Tag)

For quick prototyping or static HTML sites, load the SDK from a CDN:

<script src="https://unpkg.com/@authrim/web@latest/dist/authrim-web.umd.global.js"></script>

The global AuthrimWeb object becomes available:

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

Prerequisites

Before using the SDK, you need:

1. An Authrim instance — A running Authrim server (e.g., https://auth.example.com)
2. A client ID — Register your application in the Authrim Admin panel to get a clientId
3. Allowed Origins — Add your app’s origin (e.g., https://myapp.com) to the client’s allowed origins
4. Callback URL (for social login / OAuth) — Register https://myapp.com/callback.html as a redirect URI

Initialization

Create an Authrim client with createAuthrim():

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

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

The function is async because it initializes browser providers (crypto, storage, HTTP client) internally. Call it once at application startup and reuse the returned client.

With OAuth / OIDC

To enable OAuth features (popup login, silent auth, cross-domain SSO), set enableOAuth: true:

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

// Now auth.oauth is available
await auth.oauth.popup.login();

Quick Start: Passkey Login

Here is a minimal example that implements Passkey sign-up and sign-in:

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

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

// 2. Check if already authenticated
const isLoggedIn = await auth.session.isAuthenticated();
if (isLoggedIn) {
  console.log('Already signed in');
}

// 3. Sign up with Passkey (new user)
const signUpResult = await auth.passkey.signUp({
  email: '[email protected]',
});
if (signUpResult.error) {
  console.error('Sign up failed:', signUpResult.error.message);
} else {
  console.log('Welcome!', signUpResult.data.user);
}

// 4. Sign in with Passkey (existing user)
const loginResult = await auth.passkey.login();
if (loginResult.error) {
  console.error('Login failed:', loginResult.error.message);
} else {
  console.log('Signed in:', loginResult.data.user);
}

// 5. Sign out
await auth.signOut();

Quick Start: Email Code

// Send code
const sendResult = await auth.emailCode.send('[email protected]');
if (sendResult.error) {
  console.error(sendResult.error.message);
}

// Verify code (user enters the code they received)
const verifyResult = await auth.emailCode.verify('[email protected]', '123456');
if (verifyResult.error) {
  console.error(verifyResult.error.message);
} else {
  console.log('Authenticated:', verifyResult.data.user);
}

Quick Start: Social Login

// Popup login with Google
const result = await auth.social.loginWithPopup('google');
if (result.error) {
  console.error(result.error.message);
} else {
  console.log('Signed in via Google:', result.data.user);
}

Storage Options

By default, the SDK uses in-memory storage. This keeps browser-held state scoped to the current page lifecycle and clears it on reload/navigation. Opt into Web Storage only when your app needs reload or long-lived persistence:

const auth = await createAuthrim({
  issuer: 'https://auth.example.com',
  clientId: 'my-app',
  storage: {
    prefix: 'authrim',        // Key prefix (default: 'authrim')
    storage: 'sessionStorage', // default: 'memory'
  },
});

Type	Persistence	Security	Use Case
memory	Current page lifecycle	Most secure; no DOM storage	Default for strict browser-token flows
sessionStorage	Tab session (survives reload, cleared on tab close)	Exposed to JS in the tab	Apps that need reload persistence
localStorage	Persistent (survives browser restart)	Exposed to JS across tabs	General SDK/OAuth state only; not used for Direct Auth token persistence

Note

Direct Auth access and refresh token persistence is intentionally limited to memory or explicit sessionStorage. Passing localStorage configures the general browser storage provider used by core/OAuth state, but Direct Auth token storage falls back to memory unless sessionStorage is selected.

HTTPS Requirement

The SDK requires HTTPS in production. WebAuthn (Passkey) does not work on insecure origins.

• Production: HTTPS required
• Development: localhost and 127.0.0.1 are allowed over HTTP

Next Steps

• Example App — Walk through a complete working example
• Passkey Authentication — Deep dive into WebAuthn flows
• Email Code Authentication — OTP-based passwordless login
• Social Login — Google, GitHub, Apple and more