OnzAuth JavaScript SDK

1.0.26 verified Sat May 09 auth: no javascript

OnzAuth JavaScript SDK v1.0.26 (latest) for passwordless authentication using Email Magic Link and WebAuthN. It provides a simple popup or iframe-based login flow with automatic token storage in localStorage (access_token, id_token, refresh_token, expiry). The SDK is ESM-only (no CommonJS support) and requires a client ID from OnzAuth. It emits events ('authenticated', 'error', 'closed') and is designed for quick integration. Key differentiators: no callback URLs to configure, built-in WebAuthN support, and no password management. It is a client-side only library with a small API surface, released irregularly with bug fixes.

Common errors

error TypeError: onz.Auth is not a constructor ↓

cause Using named import `import { Auth } from 'onz-auth'` which is not exported as a named member.

fix

Use default import: import onz from 'onz-auth'; then new onz.Auth(...).

error Cannot read properties of undefined (reading 'accessToken') ↓

cause Accessing tokens before the 'authenticated' event fires, or using wrong key casing.

fix

Listen to the 'authenticated' event and use authResult.accessToken (camelCase).

error Error: Client ID is required ↓

cause Instantiated Auth without a clientID option.

fix

Provide clientID: 'your-client-id' in the Auth constructor options.

error Failed to load resource: net::ERR_BLOCKED_BY_CLIENT ↓

cause Browser blocked the popup window.

fix

Set isIframe: true to use an iframe, or allow popups for your site.

Warnings

gotcha Tokens are stored automatically in localStorage with keys: access_token, id_token, expiry, refresh_token. Do not manually manage them. ↓

fix Use the 'authenticated' event to get tokens; avoid reading from localStorage directly.

gotcha The library uses popup windows or iframes. Ensure your site allows popups (not blocked by the browser). ↓

fix Set isIframe: true to use an iframe instead, which requires a container element.

gotcha WebAuthN is disabled by default. It must be enabled in the OnzAuth project settings. ↓

fix Log in to OnzAuth dashboard > project settings > enable WebAuthN.

breaking No CommonJS support. Using require() will fail with: "ERR_REQUIRE_ESM" ↓

fix Use import statements or switch to the UMD script tag for non-module environments.

Install

npm install onz-auth

yarn add onz-auth

pnpm add onz-auth

Imports

Auth

wrong

const { Auth } = require('onz-auth'); const auth = new Auth({ clientID: '...' });

correct

import onz from 'onz-auth'; const auth = new onz.Auth({ clientID: '...' });

The default import is the module itself. Access the Auth class as onz.Auth. CommonJS require is not supported.

Auth (named import)
wrong
```
import { Auth } from 'onz-auth';
```
correct
```
import onz from 'onz-auth'; const auth = new onz.Auth({ clientID: '...' });
```
There is no named export 'Auth'. You must use the default import and access Auth via onz.Auth.

UMD script tag

wrong

<script src="https://unpkg.com/onz-auth/dist/onz-auth-js-sdk.min.js"></script>

correct

<script src="https://unpkg.com/onz-auth@1.0.26/dist/onz-auth-js-sdk.min.js"></script>

Always pin a version to avoid breaking changes. The global variable is 'onz'.

Event 'authenticated'

wrong

auth.on('authenticated', function(result) { console.log(result.accessToken); });

correct

auth.on('authenticated', (result) => { console.log(result.accessToken); });

The event emits an object with camelCase keys: accessToken, idToken, refreshToken, expiry.

Quickstart

Initializes OnzAuth, listens for authentication events, triggers a login popup, and logs the tokens. Also demonstrates error handling and logout.

import onz from 'onz-auth';

const auth = new onz.Auth({
  clientID: process.env.ONZAUTH_CLIENT_ID ?? 'your-client-id',
  containerID: 'auth-container',
  isIframe: false
});

auth.on('authenticated', (authResult) => {
  console.log('Access Token:', authResult.accessToken);
  console.log('ID Token:', authResult.idToken);
  console.log('Refresh Token:', authResult.refreshToken);
  console.log('Expiry:', authResult.expiry);
});

auth.on('error', (errorMessage) => {
  console.error('Auth error:', errorMessage);
});

auth.on('closed', () => {
  console.log('Login window closed');
});

// Show login popup
auth.showLogin();

// Later, to logout:
auth.logout();