Auth

Authenticate user on your platform

Endpoint: /action/auth

Lets a third-party application authenticate the currently logged-in WalletTwo user. The action generates a short-lived one-time token tied to that user's session and delivers it back to the host page through either a postMessage event or a redirect.

This is the first action most integrations need. You use it to know who the user is on your side without having to manage credentials yourself.

---

Required user state

Before this action runs, the router guarantees:

Check	Middleware	Redirects to if missing
User is logged in	LoggedMiddleware	/auth/login
Email is verified	EmailVerifiedMiddleware	/auth/email/verify
Wallet is created	WalletMiddleware	/auth/wallet/register

If any check fails, the iframe navigates to the appropriate onboarding screen inside the iframe. Your host page should handle this gracefully (see section below).

---

Iframe URL

https://<WALLETTWO_ORIGIN>/action/auth?iframe=true

Optional parameters:

Param	Type	Description
redirect_uri	string (absolute URL)	If provided, the iframe navigates to this URL after the token is generated
iframe	"true"	Activates bare rendering mode (no branded container, no logo). Always include this for embedded use

Full example with redirect:

https://<WALLETTWO_ORIGIN>/action/auth?iframe=true&redirect_uri=https%3A%2F%2Fexample.com%2Fwallettwo%2Fcallback

---

What happens when the action runs

1. The view immediately calls client.oneTimeToken.generate().

2. On success, it fires window.parent.postMessage(...) to the parent window.

3. If redirect_uri was supplied, the iframe navigates to that URL with additional query params appended.

4. On failure, the user sees a toast error (no redirect, no postMessage).

The iframe itself shows a looping animation video + "Redirecting…" text while the token is being generated.

---

postMessage event

Sent to window.parent as soon as the one-time token is ready.

{
  event: "wallet_login",
  type: "wallet_login",
  code: "<one-time-token>",
  user: "<wallettwo-user-id>",
  wallet: "<wallet-address>"
}

Field	Description
event	Always "wallet_login"
type	Always "wallet_login" (legacy alias, same value)
code	The one-time token. Exchange this on your backend immediately
user	WalletTwo internal user ID
wallet	The user's wallet address

The token is short-lived. Exchange it server-side as soon as your listener receives the event.

---

redirect_uri callback

If redirect_uri is present, the iframe navigates to:

<redirect_uri>?code=<token>&usr=<user-id>&wlt=<wallet-address>

Param	Description
code	Same one-time token delivered via postMessage
usr	WalletTwo user ID
wlt	Wallet address

---

Host page integration

<iframe
  id="w2-auth"
  src="https://<WALLETTWO_ORIGIN>/action/auth?iframe=true"
  style="width:420px;height:700px;border:0;"
></iframe>

<script>
  const WALLET_TWO_ORIGIN = "https://<WALLETTWO_ORIGIN>";

  window.addEventListener("message", (event) => {
    if (event.origin !== WALLET_TWO_ORIGIN) return;

    if (event.data?.event === "wallet_login") {
      const { code, user, wallet } = event.data;
      // Send `code` to your backend to verify the session
      verifySession(code, user, wallet);
    }
  });

  async function verifySession(code, user, wallet) {
    const res = await fetch("/api/auth/wallettwo", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ code, user, wallet })
    });
    const session = await res.json();
    // handle authenticated session
  }
</script>

---

Handling auth onboarding inside the iframe

If the user is not yet logged in or has not completed setup, the iframe will navigate through WalletTwo's auth flow before the auth action runs. Your host page will not receive a wallet_login event until that flow is complete.

Recommended approach:

• Keep the iframe visible and appropriately sized so onboarding screens render correctly.

• Do not set a short timeout and treat silence as failure.

• Optionally, listen for the event and set a reasonable timeout (for example, 5 minutes).

---

Security checklist

• Always verify event.origin against your known WalletTwo origin before trusting any message.

• Never log or persist the code token client-side; exchange it server-side immediately.

• Your backend must verify the one-time token with WalletTwo before creating a session.

• Validate that user and wallet in the callback match the values returned by your token verification call.