Authentication

AuthClient is the SDK 3.0 sign-in client: email+password, OTP code, OAuth (Google/Apple/…), password reset, and anonymous sessions. It persists the session locally (localStorage / chrome.storage.local / memory), refreshes the access token on a timer, and emits onAuthChange on login, refresh, and logout.

import { AuthClient } from '@monetize.software/sdk/core';
 
const auth = new AuthClient({ paywallId: 'pw_123' });
await auth.ready(); // wait for session hydration from storage
 
if (auth.getCachedUser()) {
  // user is already signed in from a previous session
}

Principles

• Single source of truth for the session — AuthClient. Any BillingClient accepts it as an option and automatically attaches Authorization: Bearer <access> to every API request, plus syncs identity from auth.user.
• Default persistence — localStorage on web, chrome.storage.local on extensions (auto-detected), in-memory as a fallback. You can supply your own StorageAdapter.
• Lazy refresh. getAccessToken() refreshes itself when expiry is less than 60s away. A network error returns the current token (still valid); a 401 on refresh signs the user out (refresh token revoked).
• Refresh deduplication. Parallel getAccessToken() calls share a single inflight refresh request to the backend.

Sign-in methods

API at a glance

Built-in login screen (gate a feature behind sign-in): paywall.openSignin()

You don’t need to build your own login UI. open() always shows the price layout, but PaywallUI also exposes dedicated handles that open the modal straight on the built-in auth screen — email/password + OAuth buttons (per settings.auth_providers), fully styled, localized, in Shadow DOM. No custom form, no provider-icon library needed.

import { PaywallUI } from '@monetize.software/sdk';
 
const paywall = new PaywallUI({ paywallId: 'pw_123', auth: true });
 
// Gate a feature behind sign-in — login only, no plans:
document.getElementById('login').onclick = () => paywall.openSignin();
 
// New-account flow (starts on the signup form):
document.getElementById('register').onclick = () => paywall.openSignup();

Use this whenever sign-in is a precondition rather than a purchase prompt:

• A returning customer already bought and just needs to log in so the SDK picks up their subscription.
• You want to require login before unlocking a feature, while keeping open() reserved for the Upgrade/plans flow.

After successful sign-in the modal closes; Back also closes it (the user came only to log in). The trial doesn’t block these flows. Without auth connected (no managed-auth) they’re a no-op — there’s no one to sign in. Symmetric to openSupport() — a short path to a single task without the full paywall flow.

Wiring with BillingClient

Pass auth to BillingClient — the token and identity will be attached automatically, no getAuthToken callback needed.

import { AuthClient, BillingClient } from '@monetize.software/sdk/core';
 
const auth = new AuthClient({ paywallId: 'pw_123' });
const billing = new BillingClient({ paywallId: 'pw_123', auth });
 
await billing.bootstrap();    // identity = auth.user; Bearer attached
const user = await billing.getUser();