Authentication

KeyWayProvider includes the complete email OTP flow. Your application opens it with login() or KeyWayLoginButton.

import { useKeyWay } from "@ckb-keyway/react";

function SignIn() {
  const { authenticated, login, logout } = useKeyWay();

  return authenticated
    ? <button onClick={() => void logout()}>Log out</button>
    : <button onClick={login}>Log in with email</button>;
}

Send a one-time code

The SDK requests an OTP from the managed KeyWay API. Backend email credentials never enter the browser.

Create a KeyWay session

A valid code returns a KeyWay session tied to a stable backend user ID.

Recover the account

The user ID maps to the same Lit PKP and CKB address on future logins.

Start Fiber

With autoConnect enabled, the SDK connects the persistent managed node by default. Optional browser mode restores its device state and starts WASM.

Session state

The SDK stores the KeyWay session in browser localStorage and validates it when the provider mounts. Use ready before reading authentication state.

const { ready, authenticated, user, status } = useKeyWay();

Value	Meaning
`ready`	Stored session validation has completed.
`authenticated`	A valid KeyWay session exists.
`user.id`	Stable backend identity for the email account.
`status`	Current authentication or connection lifecycle state.

Device behavior

Managed mode keeps the node online after logout, so another browser can reconnect to the same managed identity. In optional browser mode, KeyWay permits one active device lease per account and fails closed if another device holds it. On explicit logout, it encrypts the wallet’s Fiber IndexedDB state and uploads only ciphertext. The next device restores that state before starting Fiber.

In browser mode, closing a tab or crashing cannot guarantee a final backup. Use logout() before changing devices, and do not clear site data while signed in.

Branding

appName changes the name shown in KeyWay’s modal. theme selects the built-in light or dark appearance.

<KeyWayProvider appId="keyway_..." appName="Acme Pay" theme="dark">
  <App />
</KeyWayProvider>

appName does not alter the email itself. A developer can select existing Stytch login and signup template IDs for the registered application in the KeyWay developer console.

Get started

Build

Reference

Session state

Device behavior

Branding

​Login lifecycle

​Session state

​Device behavior

​Branding

Login lifecycle

Session state

Device behavior

Branding