@0account/web

Browser-native OAuth2/OIDC authentication widget for 0account.
Drop in a <zero-account> element — it handles PKCE, QR code, SSE polling, and redirects.

Install

npm install @0account/web

Or via CDN (no build step):

<script type="module" src="https://unpkg.com/@0account/web/dist/0account-web.js"></script>

Quickstart — Widget

The widget covers the full auth flow for you. Add the element, listen for one event.

<zero-account
  app-id="YOUR_APP_ID"
  redirect-uri="https://yourapp.com/callback"
  finalize-uri="https://yourapp.com/api/auth/finalize"
  scope="openid profile email"
  with-button
></zero-account>

import "@0account/web";

document.querySelector("zero-account")
  .addEventListener("0account-authenticated", (e) => {
    // Code exchange was handled by finalize-uri — you're done.
    console.log("logged in", e.detail);
  });

Your finalize-uri backend receives { code, code_verifier, state, nonce, redirect_uri } as JSON.
Exchange the code with 0account's /oauth/token endpoint there.

Automatic redirect after login (OIDC flow)

Add mode="redirect" and the widget navigates to redirect-uri automatically:

<zero-account
  app-id="YOUR_APP_ID"
  redirect-uri="https://yourapp.com/callback"
  finalize-uri="https://yourapp.com/api/auth/finalize"
  mode="redirect"
  with-button
></zero-account>

The callback URL includes the auth code as a query param and the session token in the hash:

https://yourapp.com/callback?code=…&state=…#za_session_token=…

Attributes

| Attribute | Required | Description | |-----------|----------|-------------| | app-id | ✅ | Your OAuth2 application ID | | redirect-uri | ✅ | OAuth redirect URI | | finalize-uri | | Your backend endpoint that receives the auth code and completes the exchange | | scope | | OAuth scopes, space-separated (default: openid profile) | | mode | | redirect — navigate to redirect-uri automatically after login | | environment | | development points to staging API | | theme | | light / dark | | embedded | | Render inline instead of as a modal | | state | | Optional OAuth state parameter | | with-button | | Show a pre-built trigger button | | label-* | | Override any UI label (e.g. label-sign-in-to) |

Events

All events fire on the <zero-account> element with bubbles: true, composed: true.

| Event | When | event.detail | |-------|------|----------------| | 0account-authenticated | Auth completes | { code, state, nonce, sessionToken, redirectUri } | | 0account-logout | Server sends logout event | { action: "logout" } | | 0account-trigger-open | Widget opens | — | | 0account-trigger-close | Widget closes | — |

Dispatch 0account-trigger-open / 0account-trigger-close on document to open/close the widget from anywhere:

document.dispatchEvent(new Event("0account-trigger-open"));

Retrieve session data after redirect

In mode="redirect", the callback page needs the PKCE verifier to exchange the code.
Read it with ZeroAccount.getSessionData() — this clears the value from sessionStorage on first call.

import { ZeroAccount } from "@0account/web";

const params = new URLSearchParams(location.search);
const code = params.get("code");
const data = ZeroAccount.getSessionData("YOUR_APP_ID"); // { verifier, nonce }

// Exchange the code on your backend
await fetch("/api/auth/finalize", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    code,
    code_verifier: data.verifier,
    state: params.get("state"),
    nonce: data.nonce,
    redirect_uri: "https://yourapp.com/callback",
  }),
});

Cross-subdomain session handoff

When redirecting a user to a different subdomain that also has the <zero-account> widget, include the session token in the URL hash — the widget reads and clears it automatically:

window.location.href = `https://app2.yoursite.com/dashboard#za_session_token=${encodeURIComponent(sessionToken)}`;

TypeScript

All types are included. Key exports:

import {
  ZeroAccount,          // Custom Element class
  ZeroAccountEvents,    // Event name constants
} from "@0account/web";

License

MIT