Skip to main content

​
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 SourceWhat the user seesPopups
walletDerived”Sign message” popup + “Sign typed data” popup2
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

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

Token Provider Flow

​
Implementation

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

MethodWhat it doesNext login
clearSession()Clears the auth token but keeps keys in memoryFast — 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. 
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: