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 sessionStorage to persist state. You can change this:

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

Type	Persistence	Security	Use Case
memory	Tab only (cleared on close)	Most secure	SPAs with strict security
sessionStorage	Tab session (cleared on tab close)	XSS-resistant	Default for most apps
localStorage	Persistent (survives browser restart)	Requires XSS protection	”Remember me” scenarios

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