> For the complete documentation index, see [llms.txt](https://onchainlabs-tech-documentation.gitbook.io/wallettwo-documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://onchainlabs-tech-documentation.gitbook.io/wallettwo-documentation/actions/auth.md).

# Auth

**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.

```js
{
  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

```html
<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.