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.

Solana-enabled sign-in

With experimental_solana, the first passkey login provisions a persistent Solana identity; later logins reuse it. Restore its state with getSession(), but do not treat the address as deployed or ready to receive. Follow Solana setup. Solana sends use the passkey retained from successful sign-in. Restoring a session without that key can return SOLANA_SIGN_IN_REQUIRED: ask the user to sign in with their passkey again. There is no caller-selected root or alternate-key fallback. A fresh authentication or wallet switch invalidates unsubmitted work; status tracking remains separate from resubmission.

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.