Skip to main content

Flows

Happy path (existing user)​

parent              iframe              auth-central API
  │                   │                       │
  │  load iframe ────▶│                       │
  │                   │  read authToken       │
  │ ◀── INIT ─────────│                       │
  │  save connId      │                       │
  │                   │                       │
  │ ── GET_SIG_MSG ──▶│                       │
  │                   │ ── POST /signature ──▶│
  │                   │ ◀── nonce, signature ─│
  │ ◀── SIG_MSG ──────│                       │
  │  sign with wallet │                       │
  │                   │                       │
  │ ── AUTH_BY_WALLET▶│                       │
  │                   │ ── POST /authenticate▶│
  │                   │ ◀── token, refresh ───│
  │ ◀── AUTH_DATA ────│                       │

New user — register and login​

If POST /web3/authenticate returns 404 (the wallet has never been used in this auth domain), the iframe automatically falls back to POST /web3/createAndAuthenticate. This is the same path that WalletsPage.onAuthFail triggers in the standard web flow (useSkipBasic(Providers.CRYPTO_WALLET_PROVIDER)). The username is generated from the wallet address (generateUsername(address)).

On success the host receives an ordinary WEB3_KIT_AUTH_DATA with payload.isNew === true — this is the signal that this is a brand-new account, and the host can route the user into onboarding instead of straight into the app. For a returning login (the previous flow) the same message carries isNew: false. On failure of the register+login call the host receives WEB3_KIT_AUTH_FAILED with reason: 'unknown'.

parent              iframe              auth-central API
  │                   │                       │
  │ ── AUTH_BY_WALLET▶│                       │
  │                   │ ── POST /authenticate▶│
  │                   │ ◀── 404 ──────────────│
  │                   │ ── POST /createAndAuthenticate ▶│
  │                   │ ◀── token, refresh ───│
  │ ◀── AUTH_DATA ────│                       │

Banned / deleted account​

POST /web3/authenticate returning 400 { error: 'User is banned' | 'User is deleted' } is mapped to a dedicated reason instead of being collapsed into unknown. The host can render a tailored error screen.

parent              iframe              auth-central API
  │ ── AUTH_BY_WALLET▶│                       │
  │                   │ ── POST /authenticate▶│
  │                   │ ◀── 400 banned/deleted│
  │ ◀── AUTH_FAILED ──│  reason: 'banned'     │
  │                   │       or 'deleted'    │

Generic failures​

Any other failure — network errors, unexpected 400/500 bodies, signature endpoint failures, failed register+login — is reported as WEB3_KIT_AUTH_FAILED with reason: 'unknown' and the original error message in payload.message (best effort).

Re-running the flow​

A given iframe instance can run multiple authentication attempts. The host simply starts another WEB3_KIT_GET_SIGNATURE_MSG cycle; the iframe issues a new nonce for each. The connectionId stays the same for the lifetime of the iframe.

When the iframe is remounted, a new connectionId is generated — discard the previous one.