Keyban Auth

Keyban Auth is a secure and modular authentication layer designed to simplify the way users access non-custodial wallets. It enables integrators to offer custom login experiences while benefiting from high-security key management and seamless wallet orchestration.

Whether you need a branded login interface, integration with an existing SSO, or support for modern authentication flows like social login or OTP, Keyban Auth adapts to your needs with minimal integration effort.

Supported authentication methods

Keyban Auth supports four authentication methods, each configurable per organization.

Email OTP

Passwordless authentication via one-time code sent to email.

Phone OTP

Passwordless authentication via SMS one-time code.

Google

OAuth 2.0 social login with Google accounts.

Auth0

Enterprise OAuth via Auth0 (configurable per organization).

Method	Type	Flow	Configuration
email-otp	Passwordless	Two steps (send then verify)	Enable/disable
phone-otp	Passwordless	Two steps (send then verify)	Enable/disable
google	Social OAuth	OAuth redirect	Enable/disable
auth0	Enterprise OAuth	OAuth redirect	Enable + domain, clientId, clientSecret

Each method is independent: an organization can enable any combination, and the SDK renders only what is enabled. The expectation is that most organizations enable at least one passwordless method (Email or Phone OTP) and optionally one social or enterprise method.

Configuration architecture

Authentication settings live on the organization record and flow top-down from the Admin Panel to the Frontend SDK. There is no per-application override — every application within the same organization sees the same authConfig.

1. Step 1

   Admin Panel

   • Authentication settings

     Toggle Email OTP, Phone OTP, Google, and Auth0 per organization. Auth0 also captures domain, clientId and clientSecret.

2. saves to
3. Step 2

   Backend (NestJS)

   • Organization.settings.authConfig

     A keyed configuration object persisted on the organization record — one entry per authentication method, with its enabled flag and any provider-specific credentials.

4. fetched by
5. Step 3

   Frontend (React SDK)

   • useKeybanAuth()

     The hook exposes the resolved config; the UI renders only the methods marked enabled — Email and Phone OTP appear as tabs, Google and Auth0 as social buttons.

Configuration flows top-down: an admin toggles methods in the Admin Panel, the backend persists the resulting authConfig on the organization record, and the Frontend SDK reads it through useKeybanAuth() to render only the enabled methods.

The contract is intentionally one-way: the SDK never writes back. Changes in the Admin Panel reach the SDK on the next config fetch — typically the next page load. This keeps the security boundary clean (only authenticated admins mutate authConfig) and avoids client-side trust assumptions.

Security model

Sensitive authentication data — email addresses, phone numbers, OTP codes — never lives in the host application's React tree. Keyban Auth solves this with the KeybanInput component, a sandboxed input rendered inside a Keyban-controlled iframe.

• Iframe isolation — every input is hosted in a Keyban-origin iframe. The host application can style the iframe container but cannot read its DOM.
• Cross-origin protection — communication between iframe and parent uses postMessage with origin checks. Values never cross the boundary as plain JavaScript variables.
• No direct access — the parent application never sees user input. It calls sendOtp() or signIn() with a reference to the input (its name); the SDK reads the value from inside the iframe and posts it directly to the Keyban backend.

The practical consequence: a compromised dependency in the host application (a rogue analytics script, a supply-chain attack on a sibling library) cannot exfiltrate auth data — it sits in a separate origin the attacker does not control.

Where the session lives

Your application is authenticated via a session cookie issued by Keyban's API and stored in the domain api.keyban.io (or api.keyban.localtest.me locally). This cookie is HTTP-Only, Secure, and SameSite-restricted — your JavaScript never reads or writes it directly. The SDK's useKeybanAuth() hook reflects the session state (isAuthenticated, user), but the session itself is always backend-controlled and tamper-proof.

Sessions and tokens

Authentication in Keyban Auth is session-based, not token-based. When a user signs in, the backend creates a session, stores it in the database, and issues a signed HTTP-Only cookie to the browser. Your React application reads the session state through useKeybanAuth() but never directly handles the session itself.

Session lifecycle:

• Lifetime — Sessions last until expiration (default ~7 days rolling window; reset on active use). If the user closes and reopens the app, the cookie is still valid as long as the browser hasn't cleared it.
• Refresh — For OAuth methods (Google, Auth0), the SDK automatically refreshes the user's credentials in the background through better-auth. You do not need to call a refresh endpoint manually.
• Expiration — When a session expires, useKeybanAuth().isAuthenticated returns false. The SDK does not refresh automatically. Your application should detect this and redirect the user to the sign-in page.

Handling expiration in your application:

1. Read useKeybanAuth() in your app shell or top-level component.
2. When isAuthenticated flips from true to false, redirect to your login page.
3. Optionally, preserve the user's current location via a ?next= query parameter so they land back where they were after re-authenticating.

See the Handle session expiration recipe for a code example.

Identity and account linking

User identity in Keyban Auth is keyed on a unique email address. One email = one user account, regardless of authentication method.

Multi-method authentication on the same email:

• Google — When you enable Google as a sign-in method, Google is marked as a trustedProvider. If a user signs in with Email OTP first (creating an account), they can later sign in with their Google account on the same email — Keyban Auth automatically links them. Both methods work on the same account with no user intervention.
• Auth0 — Mixing Auth0 with other methods on the same email is not yet supported. For Auth0 deployments, enable Auth0 as the only sign-in method. See Account linking for the current recommendation.

Your application reads the authenticated identity through useKeybanAuth().user, which always reflects the current user regardless of which method they used to sign in.

When to use which method

• Email OTP / Phone OTP — sensible defaults for consumer-facing apps. No password to forget, no third-party account required, immediate onboarding.
• Google — fastest onboarding for users who already have a Google account, but ties the user identity to a third-party provider. Good for B2C with a tech-savvy audience.
• Auth0 — required when the organization runs an enterprise SSO (Okta-style scenarios, federated SAML). The Auth0 tenant becomes the identity provider; Keyban only handles the wallet binding.

In doubt, enable Email OTP first — it has the lowest friction and is the only method that always works without any external dependency.

Next steps

• Walk through a minimal Email OTP integration: Authenticate with Email OTP.
• Add Phone OTP, Google or Auth0 to an existing setup: Authentication recipes.
• Look up the SDK surface in the auto-generated reference: useKeybanAuth and KeybanInput.