SDK Methods
Complete API reference for the Lemma JavaScript SDK
Core Methods
Most integrations only need two methods: getAuthenticatedPPID() and unlockWithRedirect().
getAuthenticatedPPID()
The primary method for authentication. Returns the user's site-specific PPID if authenticated, or instructions for what to do if not.
const wallet = new LemmaWallet();
const result = await wallet.getAuthenticatedPPID();
// result.authenticated - boolean: is the user authenticated?
// result.ppid - string: "did:lemma:ppid_abc..." (site-specific)
// result.needsRedirect - boolean: should you redirect to lemma.id?
// result.walletId - string: wallet identifier
Performance: Return-visit local checks are typically low-latency; backend verification/session binding may still be part of your flow.
1. Reads stored credential (lemma) from IndexedDB
2. Verifies Ed25519 signature locally using WebCrypto
3. Checks session unlock state (set via SSE from lemma.id)
4. Checks revocation list (local Set lookup)
These checks are typically in-memory after first page load, though integrations may still call backend endpoints.
autoAuthenticate()
Lower-level method that getAuthenticatedPPID() wraps. Returns more detail about the auth state.
const result = await wallet.autoAuthenticate();
// result.authenticated - boolean
// result.ppid - string (PPID)
// result.needsRedirect - boolean (user needs to visit lemma.id)
// result.needsPasskey - boolean (no wallet on this device)
// result.lemma - object (the signed credential)
// result.claims - object (credential claims/permissions)
// result.walletId - string
// result.source - string: 'local_lemma', 'redirect', 'global_sync'
// result.verifyTimeMs - string: verification time in ms
unlockWithRedirect(options)
Redirect the user to lemma.id to unlock their wallet. On return, the SDK automatically processes the credential.
wallet.unlockWithRedirect({
returnUrl: window.location.href // Where to come back after unlock
});
The redirect flow:
- User navigates to
lemma.id/unlock - User taps passkey (biometric verification)
- Lemma.id issues a signed credential for your site
- User redirects back with
?lemma_unlocked=1&lemma_credential=... - SDK automatically stores the credential in IndexedDB
This redirect is usually one-time per site/device pair. After that, return-visit checks are typically local and fast.
getWalletInfo()
Get current wallet state without triggering authentication.
const info = await wallet.getWalletInfo();
// info.isUnlocked - boolean: is wallet currently unlocked?
// info.walletId - string: wallet identifier (null if no wallet)
// info.hasPasskey - boolean: passkey registered on this device?
// info.hasWalletSecret - boolean: wallet secret available locally?
verifyLocalAuthorization(options?)
Directly verify a stored credential without triggering redirect flows. Useful for checking auth state silently.
const result = await wallet.verifyLocalAuthorization({
permission: 'login', // Optional: required permission (default: 'login')
siteId: window.location.hostname // Optional: override site (default: current domain)
});
// result.authorized - boolean
// result.reason - string: 'wallet_locked', 'no_lemma', 'session_expired', 'verification_failed'
// result.ppid - string (if authorized)
// result.lemma - object (if authorized)
// result.verifyTimeMs - string: time taken
Lock and Unlock (lemma.id only)
These methods are used on lemma.id itself. Third-party sites don't call these directly -- the SDK handles lock state via SSE.
// Unlock with local passkey (lemma.id only)
await wallet.unlock();
// Lock wallet (clears session everywhere via SSE)
await wallet.lock();
Events
Listen for session changes in your application:
// Wallet locked (from another device or tab)
window.addEventListener('lemma-wallet-locked', () => {
// Clear your site's session
fetch('/api/auth/logout', { method: 'POST' });
showLoginScreen();
});
// Session expired naturally (24h default)
window.addEventListener('lemma:session-expired', (e) => {
console.log('Session expired:', e.detail.reason);
showLoginScreen();
});
Debugging
Enable verbose logging to see the SDK's internal operations:
// Enable debug logging
const wallet = new LemmaWallet();
wallet._debug = true;
// Check SDK version
console.log(LemmaWallet.VERSION); // "2.50.0"