Visitor Authentication

Visitor authentication determines how a visitor proves who they are before Ezoic Subscriptions grants access or starts checkout. There are two modes:

• Ezoic visitor accounts — the default. Ezoic provides sign-in, account creation, and recovery. No integration code.
• Bring your own login — connect your existing login system to the widget through an AuthAdapter.

You select the mode in your Ezoic dashboard. The default is Ezoic visitor accounts.

How Sign-In Works

In both modes the widget resolves a visitor identity (an email address) and uses it for access checks (hasAccess) and checkout. What differs is who handles sign-in and account creation:

• Ezoic visitor accounts — Ezoic's built-in login and create-account screens, shown in the widget.
• Bring your own login — your own login and sign-up pages, reached through the callbacks you register during widget setup.

At checkout, a signed-in visitor goes straight to payment. An anonymous visitor sees an identity gate offering Log in, Create account, and — when guest checkout is enabled — Continue as a guest. Where Log in and Create account send the visitor depends on the active mode: in Ezoic visitor accounts mode they open Ezoic's built-in login and create-account screens inside the widget; in bring-your-own-login mode they call the callbacks you supply, sending the visitor to your own login and sign-up pages.

Returning visitors sign in the same way, through the active mode's provider. As a final fallback — so a paying visitor is never left without access, for example when they return on a new device — Ezoic Subscriptions can email a one-time, passwordless access link. This is a safety net, not the primary way to sign in.

Subscribers manage their billing in the subscriber portal at https://subscriber.ezoic.com.

Ezoic Visitor Accounts

This is the default mode and requires no integration code. Ezoic provides login, account creation, guest checkout (when you enable it), and passwordless recovery directly in the widget. You do not build or maintain any authentication on your site.

The widget places the Ezoic Accounts integration on the page for you. If your site already runs the Ezoic Accounts integration (window.ezAuth), leave it in place: the widget detects and reuses an existing instance and otherwise loads it itself. Either way works seamlessly, so there is nothing to add or remove.

Bring Your Own Login

Use this mode when your site already has its own login system. You connect it to the widget by registering an AuthAdapter — a small object that lets the widget read the signed-in visitor's email and send visitors to your login and sign-up pages.

The AuthAdapter Contract

For the related SDK methods and their full signatures — initialize, authChanged, and the rest of the surface — see the JavaScript API Reference.

interface AuthAdapter {
  getUserEmail: () => string | null | Promise<string | null>;
  goToLogin: () => void | Promise<void>;
  goToCreateAccount: () => void | Promise<void>;
}

getUserEmail()

Returns the signed-in visitor's email address, or null when no one is signed in. May be synchronous or return a promise.

Returns:

string | null | Promise<string | null>

The widget calls this to detect a logged-in visitor and skip the checkout identity gate. Return a syntactically valid email when the visitor is authenticated in your system; return null (or an empty/invalid value) when the visitor is anonymous.

goToLogin()

Sends the visitor to your login experience. The adapter decides how — a navigation, a modal, or a provider SDK call.

Returns:

void | Promise<void>

Powers the gate's Log in action and the paywall's "Already subscribed? Log in" link.

goToCreateAccount()

Sends the visitor to your account creation experience. The adapter decides how, exactly like goToLogin.

Returns:

void | Promise<void>

Powers the gate's Create account action. It can point at the same destination as goToLogin when your login page also registers new accounts.

Register the Adapter

Register the adapter with ezsubscriptions.initialize({ auth }) inside the cmd queue, so it is set as soon as the script is ready:

<script>
  window.ezsubscriptions = window.ezsubscriptions || {};
  ezsubscriptions.cmd = ezsubscriptions.cmd || [];
  ezsubscriptions.cmd.push(function (api) {
    api.initialize({
      auth: {
        getUserEmail: function () {
          // Return the signed-in visitor's email from your own auth, or null.
          return myAuth.getCurrentUser()?.email ?? null;
        },
        goToLogin: function () {
          window.location.href = "/login?return=" + encodeURIComponent(location.href);
        },
        goToCreateAccount: function () {
          window.location.href = "/signup?return=" + encodeURIComponent(location.href);
        },
      },
    });
  });
</script>
<script src="https://sm.ezoic.com/min.js" async defer></script>

Registration is idempotent: calling initialize again with a valid adapter replaces the previous one.

Signal Authentication Changes

Call ezsubscriptions.authChanged() whenever the visitor's login state changes — after a login, a logout, or an asynchronous session restore — so the widget re-resolves identity, refreshes the access session, and resumes any pending checkout:

async function onLogin() {
  await myAuth.signIn(/* ... */);
  await ezsubscriptions.authChanged();
}

async function onLogout() {
  await myAuth.signOut();
  await ezsubscriptions.authChanged();
}

How Checkout Uses the Adapter

• A signed-in visitor (getUserEmail() returns an email) skips the identity gate and goes straight to payment.
• An anonymous visitor sees Log in, Create account, and — when guest checkout is enabled — Continue as guest. goToLogin() and goToCreateAccount() navigate the visitor away to your pages; when they return authenticated and you call authChanged(), the widget resumes the same checkout.
• The email returned by getUserEmail() is the visitor's identity for access checks and checkout.

Guest Checkout

Guest checkout lets a visitor buy with just an email address instead of signing in or creating an account. At the identity gate the visitor chooses Continue as guest, enters an email, and pays. Access attaches to that email, so the visitor can sign in or recover access later using the same address.

Because access is tied to the email, no manual reconciliation is ever needed. If a guest later registers on your site (or already has an account) using that same email, their account — on your own login system or Ezoic visitor accounts, whichever mode you use — is linked to the purchase automatically, with no extra work for you or the visitor.

Guest checkout is a per-domain setting in your Ezoic dashboard and applies to both authentication modes.

Next Steps

• Install the widget with Onsite Script Integration.
• Gate content with the Publisher-Managed Access API.
• Review method options in the JavaScript API Reference.