@simplepasskey/browser

Browser SDK for SimplePasskey — passkey authentication as a service.

For native iOS apps, use the Swift SDK at https://github.com/spullara/simplepasskey-swift instead of the browser SDK.

Install

npm install @simplepasskey/browser @simplewebauthn/browser

Usage

import { SimplePasskey } from '@simplepasskey/browser';

const auth = new SimplePasskey({ clientId: 'your-client-id' });

// Register a new user
const { jwt, userId, refreshToken } = await auth.register({ displayName: 'Sam' });

// Sign in
const { jwt, userId, refreshToken } = await auth.signIn();

// Check auth state
if (auth.isAuthenticated()) {
  console.log('Logged in as', auth.getSession().userId);
}

// Auto-refresh on 401
const resp = await auth.fetch('/api/protected-endpoint');

// Listen for auth changes
auth.onAuthChange((session) => {
  if (session) console.log('Signed in');
  else console.log('Signed out');
});

// Logout
await auth.logout();

API

new SimplePasskey({ clientId, baseUrl?, autoRefresh? })

Create an instance. baseUrl defaults to https://api.simplepasskey.com. autoRefresh defaults to true.

auth.register({ displayName? }) → { jwt, userId, refreshToken? }

Register a new passkey. Prompts the user's authenticator and stores the returned refresh token for session restoration.

auth.signIn(options?) → { jwt, userId, refreshToken? }

Authenticate with an existing passkey. Pass { useBrowserAutofill: true } to use conditional UI (autofill) instead of a modal. When an existing session is restored silently, refreshToken may be omitted from the returned object but remains stored by the SDK.

auth.refresh() → { jwt }

Refresh an expired JWT by calling POST /auth/refresh with { refreshToken } in the JSON request body. The server response body is { jwt, refreshToken, expiresIn }; the SDK stores the rotated refreshToken and returns the new jwt.

auth.logout()

Clear the local session and call POST /auth/logout with { refreshToken } to invalidate the current refresh token server-side.

auth.getSession() → { jwt, userId, isExpired }

Get current session state.

auth.isAuthenticated() → boolean

Check if the user has a valid (non-expired) JWT.

auth.fetch(url, options?) → Response

Fetch with automatic JWT auth and 401 auto-refresh.

auth.onAuthChange(callback) → () => void

Subscribe to auth state changes. Returns an unsubscribe function.

auth.ready → Promise<Session>

A promise that resolves once auto-refresh on initialization is complete. Use await auth.ready to wait for session restoration.

Session Restoration

The SDK automatically refreshes expired JWTs on initialization:

const auth = new SimplePasskey({ clientId: 'your-client-id' });

// Wait for session restoration
const session = await auth.ready;
if (session.jwt) {
  console.log('Welcome back', session.userId);
} else {
  // Show login UI
}

Disable with autoRefresh: false if you handle refresh yourself.

Refresh tokens are single-use and rotate on every successful refresh. If a previously rotated refresh token is replayed, SimplePasskey treats it as reuse and revokes the whole refresh-token family.

Conditional UI (Autofill)

For a seamless sign-in experience, use browser autofill instead of a modal:

<input type="text" autocomplete="webauthn" placeholder="Sign in" />

// Call early on page load — the passkey appears in the autofill dropdown
const { jwt, userId } = await auth.signIn({ useBrowserAutofill: true });