@kiavi/kiavi-browser

Browser client for apps that sign users in through a Kiavi-hosted auth server.

Install

pnpm add @kiavi/kiavi-browser

Usage

import { KiaviClient } from '@kiavi/kiavi-browser'

const auth = new KiaviClient('https://auth.your-domain.com')

// Guard a route — if there's no session, the user is redirected to login.
const session = await auth.authenticate()

// Attach the token to API calls.
const token = await auth.getAccessToken()
fetch('/api/things', { headers: { Authorization: `Bearer ${token}` } })

// Sign out.
await auth.signOut()

That's the whole thing. authenticate() at the top of your app and getAccessToken() on every API call is enough for most apps.

Options

new KiaviClient('https://auth.your-domain.com', {
  locale: 'en', // adds ?lang=en to hosted pages
  debug: true, // structured console logs; pass a function to route them elsewhere
})

Reference

Methods

• authenticate(options?) — ensures a session exists. Resolves with a KiaviSession if one is already live, silently refreshable, or recovered from the auth callback. Otherwise redirects to the hosted login page and never resolves.
• getAccessToken() — returns a valid JWT, refreshing silently if the current one is near or past expiry. Throws KiaviSessionExpiredError if a new token can't be obtained.
• getSession() — non-redirecting read of the current session. Returns KiaviSession | null. Safe to call on the server.
• signOut(options?) — clears local state, revokes server-side, and redirects to the hosted signout page. Pass { redirect: false } to skip navigation.
• onAuthStateChange(listener) — subscribe to session changes. Returns an unsubscribe function.
• getAuthPolicy() — returns 'passkey_required' or 'passkey_preferred', for UI that adapts to the configured policy.
• resendVerificationEmail({ email, callbackURL? }) — unauthenticated. Asks the auth server to send another verification email. Throws KiaviAuthError on failure (code includes 'rate_limited', in which case retryAfterSeconds is populated).
• changeEmail({ newEmail, callbackURL? }) — requires an active session. Asks the auth server to change the signed-in user's email. If the current email is verified, a confirmation link is sent to the current address and the change only takes effect once the user clicks it. Throws KiaviAuthError on failure.
• setLocale(locale) / setDebugLogger(debug) — update configuration at runtime.

Types

KiaviClient, KiaviSession, KiaviSessionUser, KiaviClientOptions, KiaviAuthenticateOptions, KiaviSignOutOptions, KiaviAuthPolicy, KiaviAuthStateListener, KiaviSessionExpiredError, KiaviBrowserOnlyError, KiaviAuthError, KiaviAuthErrorCode, KiaviResendVerificationEmailOptions, KiaviChangeEmailOptions, KiaviDebugLogger, KiaviDebugLogEntry.

How it works (if you're curious)

The client talks to the Kiavi auth server at authBaseUrl. On first use it fetches /.well-known/kiavi-auth.json to discover the endpoints and capabilities of that server, then transparently uses whichever flow the server is configured for (exchange-mode PKCE or cookie mode) — you don't need to pick one.

Refresh is lazy, not timer-driven: getAccessToken() checks whether the current token is within 30 seconds of expiry and silently mints a new one if so. Concurrent callers share a single in-flight refresh. If all of that fails, the next call to authenticate() sends the user back through login.

The server-side counterpart that verifies the JWTs this client produces is @kiavi/kiavi-js.

This package is browser-only — it depends on window, sessionStorage, and fetch.