Hosted script

The module owns state, PKCE S256, callback validation, code exchange, short browser storage, and safe same-origin return paths.

Install the module

<script
  type="module"
  src="https://wamen.link/wamen.js"
  data-wamen-redirect-uri="https://app.example/callback"
  data-wamen-scope="openid"
></script>

Script attribute	Meaning
`data-wamen-redirect-uri`	Optional exact callback URL. Defaults to the current page without query or fragment.
`data-wamen-scope`	`openid`, or `openid phone`. Phone consent is never remembered.
`data-wamen-issuer`	Optional issuer override. Hosted production integrations should omit it and use the module origin.

Authorize links

<a
  data-wamen-authorize
  data-wamen-return-to="/account"
  data-wamen-scope="openid phone"
  href="https://wamen.link/authorize"
>
  Continue with WhatsApp
</a>

A link is upgraded when it has data-wamen-authorize, or when its normalized destination is https://wamen.link/authorize. Modified clicks, downloads, and target="_blank" keep native link behavior.

Completion event and navigation

wamen:authentication-complete fires only after callback state validation, code exchange, and identity storage succeed. The event is cancelable. Call event.preventDefault() synchronously when you need to await backend session creation before navigation.

window.addEventListener("wamen:authentication-complete", (event) => {
  event.preventDefault();
  const { identity, returnTo } = event.detail;
  // Await backend verification, clear identity, then navigate.
});

If no listener cancels the event, the module replaces the current location with the validated same-origin returnTo path.

Browser API

Operation	Contract
`window.Wamen.signIn(params?)`	Starts a new state and PKCE flow.
`window.Wamen.handleCallback(params?)`	Validates the callback, exchanges the code, dispatches completion, and optionally navigates.
`window.Wamen.getIdentity()`	Returns the short browser identity only before its decoded expiry. Claims are not verified in the browser.
`window.Wamen.clearIdentity()`	Removes the stored browser identity.

Do not stop at the browser

The browser token is stored in localStorage for at most 10 minutes and is readable by injected JavaScript. Send it once to your backend, verify it, create an app-owned session, then clear it.