CKB KeyWayDocs

Authentication

Understand email OTP, sessions, recovery, and device behavior.

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>;
}

Login lifecycle

Send a one-time code

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

Create a KeyWay session

A valid application-specific code returns a database-backed bearer session bound to that application and its permanent KeyWay user ID.

Recover the account

The user ID maps to the same Lit PKP and CKB account on future logins. The address stays the same unless the user turns on account recovery, which changes it once.

Start Fiber

Login only recovers the CKB identity. Call start() from useFiber() to start Fiber, or set autoStartFiber. A hosted node is already running on KeyWay's servers; a browser node restores device state and starts in the page.

Session state

The SDK stores its session in application-specific browser localStorage and validates it on mount and focus. Sessions expire after seven days and renew through Better Auth after 24 hours of age while the SDK is active. Expired or revoked sessions require login again. Use ready before reading authentication state. Application A's session cannot authorize Application B or the developer dashboard. Because the session lives in localStorage, any script that runs on your origin can read it: protect your app against XSS, for example with a strict Content Security Policy.

const { ready, authenticated, user } = useKeyWay();
ValueMeaning
readyStored session validation has completed.
authenticatedA valid KeyWay session exists.
user.idPermanent account ID within the registered application. The same email in another application has a different account and wallet.

Device behavior

A hosted node stays online after logout, so another browser can reconnect to the same node. With an optional browser node, 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 dialogs. 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. The backend uses the registered application's name with KeyWay's template and verified Resend sender. No provider template IDs are needed.

Limits

KeyWay limits sign-in codes so one app, inbox or network can't flood the system:

LimitValue
Codes per email address5 every 10 minutes
Codes per IP address60 every 10 minutes
Codes per network (IPv6 /48)60 every 10 minutes for addresses that already asked; each other address still gets its first code, up to 600
Codes to one email address from one network10 every 10 minutes; 100 from a network the user signed in from in the last 90 days, and no network cap for the IP address (IPv6 /64) they signed in from
Codes per app30 a minute, shared by all of the app's users
Codes across all appsPast 1,000 a minute, only networks people signed in from in the last 90 days get codes
Codes to one email address in one app50 every 10 minutes from new networks; networks the user signed in from in the last 90 days are exempt
Code lifetime10 minutes
Sign-in requests in progress per IP address (IPv6 /64)16, and 2 for one email address or code
Wrong attempts per code5, then request a new code
Wrong codes per email address30 a day in each app. After that, each newly requested code gets one try: a few per network and a limited number a day, and up to 20 a day from each network, and each IP address (IPv6 /64), the user signed in from in the last 90 days. A wrong code on that one try ends the code, and the modal asks for a new one

When a limit is reached, the sign-in modal shows "Too many login codes requested. Try again later". When KeyWay has too many sign-in requests waiting at once, it refuses more with "Too many sign-in requests right now. Try again in a moment" rather than making people wait without end. If your app needs more than 30 codes a minute (for a launch, say), open an issue on GitHub and we'll raise it for your app.

Recovery and logout

Better Auth verifies email ownership; KeyWay maps its permanent application account ID to the Lit PKP. Email is not converted into a private key. Login does not automatically start Fiber.

Logout revokes the backend session. Browser mode must first successfully back up its channel state; failed backup keeps the user authenticated so recovery can be retried. Legacy test accounts are not migrated into replacement accounts.

On this page