Skip to main content
Use authenticate() for both new and returning users. Start with the shared client initialization.

Authenticate

The flow proceeds in four stages:
  1. The user verifies an email or OAuth identity in the wallet dialog.
  2. The service checks for an account in your application’s smart-account namespace.
  3. WebAuthn creates or uses a passkey in your application’s top-level page.
  4. The SDK returns the account address and session metadata.
The service decides whether the account needs registration, login, or recovery. You can pass flow: "create-account" or flow: "login" to select the initial presentation, but these values are hints rather than authorization boundaries:
Enforce invite lists or other application eligibility rules before opening the dialog.

Create an application session

A successful authenticate() result proves control of the embedded wallet session. It does not create a session for your own backend. If your application needs one, issue a single-use nonce, include your domain and expiry in a message, then ask the account to sign it:
Send the exact message, signature, and account address to your backend. Verify the smart-account signature there, consume the nonce once, enforce the expiry and domain, then issue your application session. Use a verifier that supports ERC-1271 smart-account signatures.

Sign out

Also clear your application’s server session and in-memory user state. Signing out of one application does not sign the user out of another application namespace.

Error handling

Treat structured error codes as control flow. USER_CANCELLED is an expected dismissal; configuration and origin errors require an integration fix. See domain troubleshooting for checks before retrying.