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:

Your app calls authenticate()
User sees wallet popups (depending on key source and account mode — see below)
User is logged in — SDK handles everything else behind the scenes

Once authenticated, the SDK automatically attaches credentials to all API requests. Approval-only accounts additionally require a fresh wallet signature whenever permanent read keys are released from escrow.

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. Approval-only accounts are an exception: a new device, or a device without resident keys, signs once for login and once to authorize the one-time escrow export. The export signature is bound to a short-lived, single-use nonce; an unexpired bearer token alone cannot release permanent keys.

Basic Usage

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

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

let wallet = MyWalletDelegate()
let result = try await sdk.authenticate(wallet: wallet, keySource: .walletDerived())

switch result {
case .authenticated(let login):
    print(login.privacyAddress)
case .credentialRequired(let challenge):
    // Handle PIN/password prompt (see below)
    break
case .mnemonicGenerated, .recoveryRequired, .accountCreationRequired:
    // Handle every non-authenticated continuation described below.
    break
}

val wallet = MyWalletDelegate()
val result = sdk.authenticate(wallet, keySource = KeySource.WalletDerived())

when (result) {
    is AuthResult.Authenticated -> println(result.loginResult.privacyAddress)
    is AuthResult.CredentialRequired -> { /* Handle PIN/password */ }
    is AuthResult.MnemonicGenerated -> { /* Display and confirm mnemonic */ }
    is AuthResult.RecoveryRequired -> { /* Ask for recovery mnemonic */ }
    is AuthResult.AccountCreationRequired -> { /* Submit challenge.createAccountTransaction */ }
}

export PRIVACY_BOOST_APP_ID=app_abc123xyz
privacy-boost login

Approval-only EOA multichain authentication

Set approvalOnly: true on a root SDK instance. The SDK discovers chainId and the chain’s AuthRegistry from that server’s /api/v1/info; applications must not supply an AuthRegistry address. An EOA has exactly one global approval-only identity. Every chain must contain the account derived from that identity’s same owner and salt. Deployments fail closed with a conflict if an EOA has multiple approval-only accounts or if a chain contains a different account ID; such accounts require an operator-assisted migration and cannot be selected through this API. When the identity exists globally but not on the current chain, authentication returns a normal EOA transaction request:

let result = await sdk.auth.authenticate(adapter);

if (result.status === 'accountCreationRequired') {
  const currentChain = await adapter.getChainId();
  if (BigInt(currentChain) !== BigInt(result.createAccountTransaction.chainId)) {
    await switchWalletChain(result.createAccountTransaction.chainId);
  }
  await adapter.sendTransaction(result.createAccountTransaction);
  await waitForAccountCreatedIndexing(result.accountId);
  result = await sdk.auth.authenticate(adapter); // obtains a fresh basic session
}

if (result.status !== 'authenticated') {
  // Handle credentialRequired, mnemonicGenerated, and recoveryRequired.
  throw new Error(`Authentication incomplete: ${result.status}`);
}

The SDK deliberately clears the bootstrap JWT before returning accountCreationRequired, so retrying after a slow wallet transaction or indexer delay always performs a fresh login.

Multiple chains

Approval-only mode currently uses one root SDK per chain; forChain() rejects this mode because approval plans and submission state are owned by the root KeyVault. For each chain:

Create a root SDK with that chain’s serverUrl and approvalOnly: true.
Switch the wallet to the server-advertised chain before submitting a prepared transaction.
Authenticate and retain that root only while using the chain.
Call logout() and dispose() before discarding it. Do not share a root instance or its session between chains.

Approval-only trust model

Approval-only multichain recovery is an explicit exception to split-key vault confidentiality. The TEE stores a server-decryptable viewing key and can read the nullifying key associated with the identity. Always Encrypted protects these values from a SQL operator, but a compromised TEE process can recover them and becomes the account’s privacy root. These keys reveal transaction history and ownership relationships but do not authorize spends: approval-only accounts still require an on-chain approval for every spend.

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, { keySource: { 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);
}

let result = try await sdk.authenticate(wallet: wallet, keySource: .walletDerived())

switch result {
case .credentialRequired(let challenge):
    // challenge.action: .setup (first time) or .unlock (returning)
    // challenge.unlockType: .pin or .password
    let pin = showPinDialog(for: challenge)
    let login = try await sdk.submitCredential(pin)
case .authenticated(_):
    break
}

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

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, { keySource: { type: 'walletDerived' }, tokenProvider });

class MyTokenProvider: TokenProvider {
    func getToken(loginPayloadJson: String) async throws -> TokenResponse {
        var request = URLRequest(url: URL(string: "https://your-server.com/api/privacy-auth")!)
        request.httpMethod = "POST"
        request.setValue("application/json", forHTTPHeaderField: "Content-Type")
        request.httpBody = loginPayloadJson.data(using: .utf8)

        let (data, _) = try await URLSession.shared.data(for: request)
        let json = try JSONSerialization.jsonObject(with: data) as! [String: Any]
        return TokenResponse(
            token: json["token"] as! String,
            expiresIn: json["expiresIn"] as! UInt64
        )
    }
}

try await sdk.authenticate(wallet: wallet, tokenProvider: MyTokenProvider())

class MyTokenProvider : TokenProvider {
    override suspend fun getToken(loginPayloadJson: String): TokenResponse {
        val response = httpClient.post("https://your-server.com/api/privacy-auth") {
            contentType(ContentType.Application.Json)
            setBody(loginPayloadJson)
        }
        val json = Json.parseToJsonElement(response.bodyAsText()).jsonObject
        return TokenResponse(
            token = json["token"]!!.jsonPrimitive.content,
            expiresIn = json["expiresIn"]!!.jsonPrimitive.long.toULong()
        )
    }
}

sdk.authenticate(wallet, tokenProvider = MyTokenProvider())

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.

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

sdk.clearSession()
sdk.logout()

sdk.clearSession()
sdk.logout()

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

Quickstart

Setup

SDKs

Authentication

Authentication

Choosing an Auth Method

User Experience

Wallet Popups

Returning Users

Basic Usage

Approval-only EOA multichain authentication

Multiple chains

Approval-only trust model

PIN / Password Unlock

Token Providers

How it works

Implementation

Logging Out

Next Steps

API Secret

Custom JWT

Privy

Dynamic

​Authentication

​Choosing an Auth Method

​User Experience

​Wallet Popups

​Returning Users

​Basic Usage

​Approval-only EOA multichain authentication

​Multiple chains

​Approval-only trust model

​PIN / Password Unlock

​Token Providers

​How it works

​Implementation

​Logging Out

​Next Steps

API Secret

Custom JWT

Privy

Dynamic

Authentication

Choosing an Auth Method

User Experience

Wallet Popups

Returning Users

Basic Usage

Approval-only EOA multichain authentication

Multiple chains

Approval-only trust model

PIN / Password Unlock

Token Providers

How it works

Implementation

Logging Out

Next Steps