Privy Integration

Privy provides embedded wallets, social login, and user management for web3 apps. You can use Privy as your auth provider for Privacy Boost, letting users log in with email, social accounts, or wallets through Privy while using Privacy Boost for private transactions.

How It Works

Privy authenticates your users and issues JWTs. The SDK can attach the raw Privy token to Privacy Boost’s login flow directly, and Privacy Boost validates the token against Privy’s JWKS endpoint.

Server-Side Setup

Your app must be configured with the privy_jwt auth method. Contact the Privacy Boost team with:

Privy App ID — Your Privy application ID (found in the Privy Dashboard)
JWKS URL — Privy’s JWKS endpoint: https://auth.privy.io/api/v1/apps/<YOUR_PRIVY_APP_ID>/.well-known/jwks.json

The backend configuration looks like:

{
  "privy_app_id": "clx...",
  "jwks_url": "https://auth.privy.io/api/v1/apps/clx.../.well-known/jwks.json"
}

Client-Side Integration

1. Set Up Privy

Follow Privy’s React quickstart to set up PrivyProvider:

import { PrivyProvider } from '@privy-io/react-auth';

function App() {
  return (
    <PrivyProvider appId="clx..." config={{ /* ... */ }}>
      <YourApp />
    </PrivyProvider>
  );
}

2. Configure Privacy Boost for Direct IdP Auth

Browser IdP callbacks are only supported in local key-vault mode. The default browser mode is the isolated iframe vault, which intentionally does not accept host-page token callbacks.

import { PrivacyBoost } from '@sunnyside-io/privacy-boost';

const sdk = new PrivacyBoost({
  serverUrl: 'https://optimism.sepolia.privacyboost.io',
  appId: 'app_abc123xyz',
  keyVault: { mode: 'local' },
});

3. Create an External Token Callback

The callback returns the raw Privy auth token. The SDK attaches it to both the /auth/login bootstrap and /auth/token exchange:

import { usePrivy } from '@privy-io/react-auth';

function usePrivacyBoostAuth() {
  const { getAccessToken } = usePrivy();

  const getExternalToken = async () => {
    const privyToken = await getAccessToken();
    if (!privyToken) throw new Error('Not logged in to Privy');
    return privyToken;
  };

  return { getExternalToken };
}

4. Authenticate with Privacy Boost

const { getExternalToken } = usePrivacyBoostAuth();

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

Optional: Backend Relay Instead

If you prefer to keep all auth exchanges behind your own backend, use tokenProvider instead of getExternalToken. The options are mutually exclusive. Your backend receives the SDK’s login payload, verifies the Privy token, and forwards to Privacy Boost:

const tokenProvider = async (loginPayload: any) => {
  const privyToken = await getExternalToken();
  const res = await fetch('https://your-backend.com/api/privacy-boost/auth', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${privyToken}`,
    },
    body: JSON.stringify(loginPayload),
  });
  return await res.json(); // { token, expiresIn }
};

app.post('/api/privacy-boost/auth', async (req, res) => {
  const toPrivacyBoostAuthPayload = (payload: any) => ({
    grant_type: payload.grantType,
    app_id: payload.appId,
    client_id: payload.clientId,
    client_secret: payload.clientSecret,
    mpk: payload.mpk,
    viewauth_signature: payload.viewauthSignature,
    nonce: payload.nonce,
    account_id: payload.accountId,
    account_salt: payload.accountSalt,
    viewing_public_key: payload.viewingPublicKey,
    nullifying_key: payload.nullifyingKey,
    wallet_address: payload.walletAddress,
    auth_pk_x: payload.authPkX,
    auth_pk_y: payload.authPkY,
    auth_expiry: payload.authExpiry,
    auth_signature: payload.authSignature,
  });

  // 1. Extract Privy token from Authorization header
  const privyToken = req.headers.authorization?.replace('Bearer ', '');
  if (!privyToken) return res.status(401).json({ error: 'Missing Privy token' });

  // 2. Forward to Privacy Boost with the Privy token attached
  const pbResponse = await fetch('https://optimism.sepolia.privacyboost.io/auth/token', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      ...toPrivacyBoostAuthPayload(req.body), // SDK camelCase payload -> /auth/token wire payload
      privy_token: privyToken, // Privy JWT — Privacy Boost validates this via JWKS
    }),
  });

  const data = await pbResponse.json();
  res.json({
    token: data.access_token,
    expiresIn: data.expires_in,
  });
});

You don’t need to validate the Privy JWT yourself. Privacy Boost fetches Privy’s JWKS and verifies the token signature, audience, and expiry.

Using Privy’s Embedded Wallet

If your users use Privy’s embedded wallet (no MetaMask), you can create a wallet adapter from Privy’s wallet provider:

import { useWallets } from '@privy-io/react-auth';

function usePrivyWalletAdapter() {
  const { wallets } = useWallets();
  const embeddedWallet = wallets.find((w) => w.walletClientType === 'privy');

  const getAdapter = async () => {
    if (!embeddedWallet) throw new Error('No embedded wallet');
    const provider = await embeddedWallet.getEthereumProvider();

    return {
      async connect() {
        const accounts = await provider.request({ method: 'eth_requestAccounts' });
        const chainId = await provider.request({ method: 'eth_chainId' });
        return { address: accounts[0], chainId: parseInt(chainId, 16) };
      },
      async disconnect() {},
      async signMessage(message: string) {
        const accounts = await provider.request({ method: 'eth_accounts' });
        return provider.request({ method: 'personal_sign', params: [message, accounts[0]] });
      },
      async signTypedData(typedData: string) {
        const accounts = await provider.request({ method: 'eth_accounts' });
        return provider.request({ method: 'eth_signTypedData_v4', params: [accounts[0], typedData] });
      },
      async sendTransaction(tx: unknown) {
        return provider.request({ method: 'eth_sendTransaction', params: [tx] });
      },
      async getAddress() {
        const accounts = await provider.request({ method: 'eth_accounts' });
        return accounts[0];
      },
      async getChainId() {
        const chainId = await provider.request({ method: 'eth_chainId' });
        return parseInt(chainId, 16);
      },
    };
  };

  return { getAdapter, hasWallet: !!embeddedWallet };
}

Next Steps

Continue with setup:

Key Management — Configure key persistence for returning users
Error Handling — Handle auth and operation errors

Or explore other auth methods:

Custom JWT — For Auth0, Firebase, Supabase, Clerk, or OIDC providers
Dynamic — For Dynamic wallet connection and embedded wallets

Quickstart

Setup

SDKs

Privy Integration

Privy Integration

How It Works

Server-Side Setup

Client-Side Integration

1. Set Up Privy

2. Configure Privacy Boost for Direct IdP Auth

3. Create an External Token Callback

4. Authenticate with Privacy Boost

Optional: Backend Relay Instead

Using Privy’s Embedded Wallet

Next Steps

​Privy Integration

​How It Works

​Server-Side Setup

​Client-Side Integration

​1. Set Up Privy

​2. Configure Privacy Boost for Direct IdP Auth

​3. Create an External Token Callback

​4. Authenticate with Privacy Boost

​Optional: Backend Relay Instead

​Using Privy’s Embedded Wallet

​Next Steps

Privy Integration

How It Works

Server-Side Setup

Client-Side Integration

1. Set Up Privy

2. Configure Privacy Boost for Direct IdP Auth

3. Create an External Token Callback

4. Authenticate with Privacy Boost

Optional: Backend Relay Instead

Using Privy’s Embedded Wallet

Next Steps