Authentication

Connect a wallet, derive keys, and log in to Privacy Boost

Authentication

Authentication is a single authenticate() call that connects the user’s wallet, derives their privacy keys, and obtains an access token from the server. After authentication, the user has a privacy address — a public identifier (separate from their Ethereum address) that others use to send them private transfers. See Key Management for details on key derivation.

Choosing an Auth Method

Before integrating authentication, choose how your app verifies users. See the auth method comparison table in App Setup.

For development, the SDK authenticates directly — no backend needed. For production, you’ll route authentication through your backend using a token provider.

User Experience

From the user’s perspective, authentication looks like this:

1. Your app calls authenticate()
2. User sees 1-2 wallet popups (depending on key source — see below)
3. User is logged in — SDK handles everything else behind the scenes

Once authenticated, the SDK automatically attaches credentials to all API requests. The user does not need to sign anything again until they log out or their session expires.

Wallet Popups

The number of wallet signature requests depends on how keys are derived:

Key Source	What the user sees	Popups
walletDerived	”Sign message” popup + “Sign typed data” popup	2
mnemonic	”Sign typed data” popup only (keys come from the mnemonic)	1
rawSeed	”Sign typed data” popup only (keys come from the seed)	1

The first popup (when using walletDerived) asks the user to sign a message to derive their privacy keys. The second popup registers an authorization key on-chain. Both are one-time per session.

Returning Users

When a user returns to your app and their session is still saved (via persistence or manual session import), they can re-authenticate with zero wallet popups. The SDK uses the stored keys and only refreshes the server token.

Basic Usage

TypeScript

const result = await sdk.auth.authenticate(walletAdapter, { type: 'walletDerived' });

if (result.status === 'authenticated') {
  console.log(result.privacyAddress);
}

PIN / Password Unlock

If you’ve configured persistence with pin or password unlock, authenticate() may return credentialRequired instead of logging in immediately. This happens when:

• First time — The SDK needs a PIN/password to encrypt the key vault
• Returning user — The SDK needs the PIN/password to decrypt the stored keys

TypeScript

const result = await sdk.auth.authenticate(adapter, { type: 'walletDerived' });

if (result.status === 'credentialRequired') {
  // Show a PIN or password input to the user
  const pin = await showPinDialog(result.action); // 'setup' or 'unlock'
  const login = await result.submit(pin);
  console.log(login.privacyAddress);
}

If persistence uses biometric or passkey unlock, the platform prompt appears automatically — no extra code needed.

Token Providers

A token provider is a function you pass to authenticate() that routes the login request through your backend. Your backend adds credentials (API secret, Privy token, or custom JWT) before forwarding to Privacy Boost. This keeps secrets out of client-side code.

When do you need one? Only if your app uses API secret, Privy, or custom JWT authentication. For direct auth (development), no token provider is needed. See App Setup for details.

How it works

Implementation

TypeScript

const tokenProvider = async (payload) => {
  const res = await fetch('https://your-server.com/api/privacy-auth', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(payload),
  });
  return await res.json(); // { token, expiresIn }
};

await sdk.auth.authenticate(adapter, { type: 'walletDerived', tokenProvider });

The token provider receives the SDK’s login payload (a JSON object with all the cryptographic proofs) and must return { token: string, expiresIn: number }.

Never expose API secrets in client-side code. Use a custom token provider to route authentication through your backend.

Logging Out

Method	What it does	Next login
clearSession()	Clears the auth token but keeps keys in memory	Fast — no wallet popups needed
logout()	Clears everything (keys, token, connection)	Full re-auth with wallet popups

Use clearSession() when you want to expire the token but let the user quickly re-login (e.g., switching accounts on the server side). Use logout() for a full sign-out.

TypeScript

sdk.auth.clearSession();  // Quick re-login possible
sdk.auth.logout();        // Full sign-out

Next Steps

If you’re using a production auth method, set up your integration next:

API Secret

Server-to-server authentication with client credentials

Custom JWT

Auth0, Firebase, Supabase, Clerk, or any OIDC provider

Privy

Social login and embedded wallets via Privy

Dynamic

Wallet connection and embedded wallets via Dynamic

Then continue with setup:

• Key Management — Choose a key source and configure persistence
• Error Handling — Handle auth and operation errors
• Keys & Encryption — Deep dive into how auth keys, viewing keys, and privacy addresses work