@kiavi/kiavi-browser

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

Install

pnpm add @kiavi/kiavi-browser

After install, the package automatically writes its version-pinned integration guide to .kiavi/kiavi-browser.md and adds a reference block to your repo's AGENTS.md (or CLAUDE.md). If your package manager blocks dependency scripts, run npx kiavi-browser init for a manual refresh and approval guidance. See AI agent docs for the full picture.

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

The auth base URL is the only identity/configuration value the SDK needs. It discovers the auth mode and app slug from /.well-known/kiavi-auth.json; in exchange mode it derives the web client ID as <app-slug>-web. Authentication policy remains an auth-server concern.

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.
• 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.
• getProfile() — returns the authenticated user's social profile snapshot ({ name, picture, provider }) as captured by the IdP at sign-in time. Returns null if the user is unauthenticated or signed in without a social provider (passkey-only, magic-link-only). Kiavi does not refresh this data — call the provider's API yourself if you need fresh values.
• setLocale(locale) / setDebugLogger(debug) — update configuration at runtime.

Types

KiaviClient, KiaviSession, KiaviSessionUser, KiaviProfile, KiaviClientOptions, KiaviAuthenticateOptions, KiaviSignOutOptions, 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 the small /.well-known/kiavi-auth.json discovery document to learn the auth mode and app slug. Endpoint paths are derived from the base URL, and the exchange-mode web client ID is derived from the slug, so you don't configure those separately.

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.