{"id":28009,"library":"onz-auth","title":"OnzAuth JavaScript SDK","description":"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.","status":"active","version":"1.0.26","language":"javascript","source_language":"en","source_url":"https://github.com/zailky/onz-auth-js","tags":["javascript","login","signin","authentication","authorisation","signup","openid","auth","jwt"],"install":[{"cmd":"npm install onz-auth","lang":"bash","label":"npm"},{"cmd":"yarn add onz-auth","lang":"bash","label":"yarn"},{"cmd":"pnpm add onz-auth","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The default import is the module itself. Access the Auth class as onz.Auth. CommonJS require is not supported.","wrong":"const { Auth } = require('onz-auth'); const auth = new Auth({ clientID: '...' });","symbol":"Auth","correct":"import onz from 'onz-auth'; const auth = new onz.Auth({ clientID: '...' });"},{"note":"There is no named export 'Auth'. You must use the default import and access Auth via onz.Auth.","wrong":"import { Auth } from 'onz-auth';","symbol":"Auth (named import)","correct":"import onz from 'onz-auth'; const auth = new onz.Auth({ clientID: '...' });"},{"note":"Always pin a version to avoid breaking changes. The global variable is 'onz'.","wrong":"<script src=\"https://unpkg.com/onz-auth/dist/onz-auth-js-sdk.min.js\"></script>","symbol":"UMD script tag","correct":"<script src=\"https://unpkg.com/onz-auth@1.0.26/dist/onz-auth-js-sdk.min.js\"></script>"},{"note":"The event emits an object with camelCase keys: accessToken, idToken, refreshToken, expiry.","wrong":"auth.on('authenticated', function(result) { console.log(result.accessToken); });","symbol":"Event 'authenticated'","correct":"auth.on('authenticated', (result) => { console.log(result.accessToken); });"}],"quickstart":{"code":"import onz from 'onz-auth';\n\nconst auth = new onz.Auth({\n  clientID: process.env.ONZAUTH_CLIENT_ID ?? 'your-client-id',\n  containerID: 'auth-container',\n  isIframe: false\n});\n\nauth.on('authenticated', (authResult) => {\n  console.log('Access Token:', authResult.accessToken);\n  console.log('ID Token:', authResult.idToken);\n  console.log('Refresh Token:', authResult.refreshToken);\n  console.log('Expiry:', authResult.expiry);\n});\n\nauth.on('error', (errorMessage) => {\n  console.error('Auth error:', errorMessage);\n});\n\nauth.on('closed', () => {\n  console.log('Login window closed');\n});\n\n// Show login popup\nauth.showLogin();\n\n// Later, to logout:\nauth.logout();","lang":"javascript","description":"Initializes OnzAuth, listens for authentication events, triggers a login popup, and logs the tokens. Also demonstrates error handling and logout."},"warnings":[{"fix":"Use the 'authenticated' event to get tokens; avoid reading from localStorage directly.","message":"Tokens are stored automatically in localStorage with keys: access_token, id_token, expiry, refresh_token. Do not manually manage them.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Set isIframe: true to use an iframe instead, which requires a container element.","message":"The library uses popup windows or iframes. Ensure your site allows popups (not blocked by the browser).","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Log in to OnzAuth dashboard > project settings > enable WebAuthN.","message":"WebAuthN is disabled by default. It must be enabled in the OnzAuth project settings.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Use import statements or switch to the UMD script tag for non-module environments.","message":"No CommonJS support. Using require() will fail with: \"ERR_REQUIRE_ESM\"","severity":"breaking","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-05-09T00:00:00.000Z","next_check":"2026-08-07T00:00:00.000Z","problems":[{"fix":"Use default import: `import onz from 'onz-auth';` then `new onz.Auth(...)`.","cause":"Using named import `import { Auth } from 'onz-auth'` which is not exported as a named member.","error":"TypeError: onz.Auth is not a constructor"},{"fix":"Listen to the 'authenticated' event and use `authResult.accessToken` (camelCase).","cause":"Accessing tokens before the 'authenticated' event fires, or using wrong key casing.","error":"Cannot read properties of undefined (reading 'accessToken')"},{"fix":"Provide clientID: 'your-client-id' in the Auth constructor options.","cause":"Instantiated Auth without a clientID option.","error":"Error: Client ID is required"},{"fix":"Set isIframe: true to use an iframe, or allow popups for your site.","cause":"Browser blocked the popup window.","error":"Failed to load resource: net::ERR_BLOCKED_BY_CLIENT"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}