Whitelabel - Privy Docs

The Privy React SDK provides complete control over all interfaces for authentication, embedded wallets, and user management. You can customize the user experience to match your brand while maintaining the security and reliability of Privy’s infrastructure.

The fastest way to get started with whitelabeling is to fork our whitelabel starter repository. This template provides a fully customizable foundation that you can build upon.

What you can customize

Authentication flows

Whitelabel login and MFA with your own UI and branding.

Embedded wallets

Create seamless wallet interactions with your own UI components and styling.

User management

Manage user profiles and connect social accounts your way.

Whitelabeling your app

Privy allows developers to choose when to take advantage of Privy’s UI and when to customize the experience with their own UI. This guide walks through how to whitelabel your app.

Authentication

All of Privy’s authentication flows can be whitelabeled, from email and SMS passwordless flows to social logins and passkeys.

To whitelabel Privy’s passwordless email flow, use the useLoginWithEmail hook. Then, call sendCode and loginWithCode with the desired email address.

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

const {sendCode, loginWithCode} = useLoginWithEmail();
sendCode({email: '[email protected]'});
loginWithCode({code: '123456'});

Learn more about email authentication and tracking login flow state.

SMS

To whitelabel the passwordless SMS flow, use the useLoginWithSms hook. Then, call sendCode and loginWithCode with the desired phone number.

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

const {sendCode, loginWithCode} = useLoginWithSms();
sendCode({phoneNumber: '+1234567890'});
loginWithCode({code: '123456'});

Learn more about SMS authentication and tracking login flow state.

Social logins

To whitelabel social login, use the useLoginWithSocial hook and call initOAuth with your desired social login provider.

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

const {initOAuth} = useLoginWithSocial();
initOAuth({provider: 'google'});

Learn more about social logins and tracking login flow state.

Passkeys

To whitelabel passkeys, use the useLoginWithPasskey hook and call loginWithPasskey.

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

const {loginWithPasskey} = useLoginWithPasskey();
loginWithPasskey();

To sign up with a passkey:

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

const {signupWithPasskey} = useSignupWithPasskey();
signupWithPasskey();

To link a passkey to an existing user:

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

const {linkWithPasskey} = useLinkWithPasskey();
linkWithPasskey();

Learn more about passkeys and tracking login flow state.

To whitelabel the Telegram login flow, it’s as simple as using the useLoginWithTelegram hook and calling login.

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

const {login, state} = useLoginWithTelegram();
login();

Learn more about Telegram authentication and tracking login flow state.

MFA

To whitelabel MFA with SMS, TOTP, or passkeys, follow the custom UI guide.

Wallets

Privy enables developers to whitelabel embedded wallet functionality. You can abstract away wallet UIs entirely or selectively use Privy’s default UI for specific flows. To whitelabel embedded wallets, you can configure this globally across your app in the PrivyProvider config, or selectively for specific flows at runtime.

Provider config (globally)

In your PrivyProvider config you can control the default wallet UI for all flows in your app.

<PrivyProvider
  appId={process.env.NEXT_PUBLIC_PRIVY_APP_ID || ''}
  config={{
    embeddedWallets: {
      showWalletUIs: false,
      priceDisplay: {primary: 'native-token', secondary: null}
    }
  }}
>
  <YourApp />
</PrivyProvider>

For more granular control, you can also control wallet UIs for specific flows in the sections below.

Create a wallet

Privy supports whitelabeling wallet creation for Ethereum, Solana, and other chains.

Ethereum
Solana
Other chains

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

const {createWallet} = useCreateWallet();
createWallet();

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

const {createWallet} = useWallets();
createWallet();

import {useCreateWallet} from '@privy-io/react-auth/extended-chains';

const {createWallet} = useCreateWallet();
const {user, wallet} = await createWallet({chainType: 'cosmos'}); // or 'stellar', 'sui', etc.

Signing a message

To whitelabel Privy’s message signing functionality, use the useSignMessage hook and call signMessage with your desired message.

Ethereum
Solana
Other chains

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

const {signMessage} = useSignMessage();
const signature = await signMessage(
  {message: 'Hello, world!'},
  {uiOptions: {showWalletUIs: false}}
);

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

const {signMessage} = useSignMessage();
signMessage({
  message: 'messageinUint8Array',
  options: {uiOptions: {showWalletUIs: false}}
});

import {useSignRawHash} from '@privy-io/react-auth/extended-chains';

const {signature} = await signRawHash({
  address: 'insert-wallet-address',
  chainType: 'cosmos', // or 'stellar', 'sui', etc.
  hash: '0x1acab030f479bda7829de07e9db4138cec5d38574df17d65af1617b7268541c0'
});

Sending a transaction

To whitelabel Privy’s transaction sending functionality, use the useSendTransaction hook and call sendTransaction with your desired transaction.

Ethereum
Solana

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

const {sendTransaction} = useSendTransaction();
sendTransaction(
  {
    to: '0xE3070d3e4309afA3bC9a6b057685743CF42da77C',
    value: 100000
  },
  {
    uiOptions: {showWalletUIs: false}
  }
);

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

const {sendTransaction} = useSendTransaction();
sendTransaction({
  transaction: 'insert-solana-transaction',
  uiOptions: {showWalletUIs: false}
});

User management

Privy supports whitelabeling user management for linking and unlinking accounts.

Linking a social account

To whitelabel linking social accounts, use the useLinkAccount hook and call link<Provider>.

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

const {linkGoogle, linkTwitter} = useLinkAccount();
linkGoogle();
linkTwitter();

Linking a wallet

To whitelabel linking wallets, use the useLinkWithSiwe hook for Ethereum wallets or useLinkWithSiws hook for Solana wallets. These hooks allow you to generate messages, request signatures, and link wallets without using Privy’s modal UI.

Ethereum (SIWE)
Solana (SIWS)

To link an Ethereum wallet to a user via SIWE, use the React SDK’s useLinkWithSiwe hook.

Generate SIWE message

generateSiweMessage({ address: string, chainId: string }) => Promise<string>

Show Parameters

address

string

required

EIP-55 checksum-encoded wallet address performing the signing.

chainId

string

required

The chain ID to which the session is bound, in CAIP-2 format, e.g. 'eip155:1'.

Sign the SIWE message

Request an EIP-191 personal_sign signature for the message returned by generateSiweMessage from the wallet.

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

const {wallets} = useWallets();
const signature = await wallets[0].sign(message);

Alternatively, you can request a signature from any external wallet or smart account:

const signature = await wallet.signMessage({message});

Link with SIWE

linkWithSiwe({
  signature: string,
  message: string,
  chainId: string,
  walletClientType?: string,
  connectorType?: string
}) => Promise<void>

Show Parameters

signature

string

required

The EIP-191 signature corresponding to the message.

message

string

required

The EIP-4361 message returned by generateSiweMessage.

chainId

string

required

The same CAIP-2 formatted chain ID you passed to generateSiweMessage, e.g. 'eip155:1'.

walletClientType

string

Optional. The wallet client of the external wallet (e.g., 'metamask', 'coinbase_wallet'). Defaults to null if not specified.

connectorType

string

Optional. The method used to connect the wallet to the application (e.g., 'injected', 'wallet_connect_v2'). Defaults to null if not specified.

Usage

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

export function LinkWalletButton() {
  const {generateSiweMessage, linkWithSiwe} = useLinkWithSiwe();
  const {wallets} = useWallets();

  const handleLink = async () => {
    if (!wallets?.length) return;
    const activeWallet = wallets[0];

    const message = await generateSiweMessage({
      address: activeWallet.address,
      chainId: 'eip155:1'
    });

    const signature = await activeWallet.sign(message);
    await linkWithSiwe({
      message,
      chainId: 'eip155:1',
      signature
    });
  };

  return <button onClick={handleLink}>Link wallet</button>;
}

Callbacks

You can optionally pass callbacks into useLinkWithSiwe:

const {generateSiweMessage, linkWithSiwe} = useLinkWithSiwe({
  onSuccess: ({user, linkMethod, linkedAccount}) => {
    console.log('Wallet linked successfully', linkedAccount);
  },
  onError: (error) => {
    console.error('Failed to link wallet', error);
  }
});

To link a Solana wallet to a user via SIWS, use the React SDK’s useLinkWithSiws hook.

Generate SIWS message

generateSiwsMessage({ address: string }) => Promise<string>

Show Parameters

address

string

required

The Solana wallet address performing the signing.

Sign the SIWS message

Request a signature for the message returned by generateSiwsMessage from the Solana wallet. The message needs to be encoded as Uint8Array for signing.

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

const {wallets} = useWallets();
const encodedMessage = new TextEncoder().encode(message);
const results = await wallets[0].signMessage({message: encodedMessage});

Link with SIWS

linkWithSiws({
  message: string,
  signature: string,
  walletClientType?: string,
  connectorType?: string
}) => Promise<{ user: User; linkedAccount: LinkedAccountWithMetadata | null }>

Show Parameters

message

string

required

The SIWS message returned from generateSiwsMessage.

signature

string

required

The signature corresponding to the message. Convert the signature bytes from the wallet’s signMessage method to a base64-encoded string using Buffer.from(results.signature).toString('base64').

walletClientType

string

Optional. A string indicating the wallet client you’d like to associate with the wallet. Defaults to 'privy'.

connectorType

string

Optional. A string indicating the connector type you’d like to associate with the wallet. Defaults to 'privy'.

Usage

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

export function LinkSolanaWalletButton() {
  const {generateSiwsMessage, linkWithSiws} = useLinkWithSiws();
  const {wallets} = useWallets();

  const handleLink = async () => {
    if (!wallets?.length) return;
    const activeWallet = wallets[0];

    const message = await generateSiwsMessage({
      address: activeWallet.address
    });

    const encodedMessage = new TextEncoder().encode(message);
    const results = await activeWallet.signMessage({message: encodedMessage});

    // Convert signature bytes to string (base64)
    const signatureBase64 = Buffer.from(results.signature).toString('base64');

    await linkWithSiws({
      message,
      signature: signatureBase64
    });
  };

  return <button onClick={handleLink}>Link Solana wallet</button>;
}

Callbacks

You can optionally pass callbacks into useLinkWithSiws:

const {generateSiwsMessage, linkWithSiws} = useLinkWithSiws({
  onSuccess: ({user, linkMethod, linkedAccount}) => {
    console.log('Solana wallet linked successfully', linkedAccount);
  },
  onError: (error) => {
    console.error('Failed to link Solana wallet', error);
  }
});

Updating an email

To whitelabel updating a user’s email address, use the useUpdateEmail hook:

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

const {state, sendCode, verifyCode} = useUpdateEmail();

Send an OTP

First, use the sendCode method to send an OTP verification code to the user’s new email address:

sendCode: ({newEmailAddress: string}) => Promise<void>;

Show Parameters

newEmailAddress

string

required

The new email address to send the verification code to.

This sends a one-time passcode to the new email address, which the user must enter to verify and confirm the update.

Verify the OTP

Prompt the user for the OTP they received and verify it using the verifyCode method:

verifyCode: ({code: string}) => Promise<{user: User} | undefined>;

Show Parameters

code

string

required

The one-time code received on the new email address.

Show Returns

user

User

The updated user object if the update was successful.

State

The state property provides the current state of the OTP flow:

Status	Description
`'initial'`	The flow has not started
`'sending-code'`	The code is being sent
`'awaiting-code-input'`	Waiting for the user to enter the code
`'submitting-code'`	The code is being verified
`'done'`	The email was updated successfully
`'error'`	An error occurred (includes an `error` field)

Usage

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

function UpdateEmailForm() {
  const {state, sendCode, verifyCode} = useUpdateEmail();
  const [newEmailAddress, setNewEmailAddress] = useState('');
  const [code, setCode] = useState('');

  if (state.status === 'initial' || state.status === 'sending-code') {
    return (
      <div>
        <input
          type="email"
          value={newEmailAddress}
          onChange={(e) => setNewEmailAddress(e.target.value)}
          placeholder="New email address"
        />
        <button
          onClick={() => sendCode({newEmailAddress})}
          disabled={state.status === 'sending-code'}
        >
          Send code
        </button>
      </div>
    );
  }

  return (
    <div>
      <input
        value={code}
        onChange={(e) => setCode(e.target.value)}
        placeholder="Enter verification code"
      />
      <button onClick={() => verifyCode({code})} disabled={state.status === 'submitting-code'}>
        Verify
      </button>
    </div>
  );
}

Callbacks

You can optionally pass callbacks into useUpdateEmail:

const {state, sendCode, verifyCode} = useUpdateEmail({
  onSuccess: ({user, updateMethod, updatedAccount}) => {
    console.log('Email updated successfully', user);
  },
  onError: (error, details) => {
    console.error('Failed to update email', error, details);
  }
});

Show Callback parameters

onSuccess

({user: User, updateMethod: string, updatedAccount: LinkedAccountType}) => void

Optional callback that executes after a successful email update. Receives the updated user object, the update method ('email'), and the updated account.

onError

(error: PrivyErrorCode, details: {linkMethod: string}) => void

Optional callback that executes if there is an error during the email update flow.

Unlinking an account

To whitelabel unlinking an account, use the usePrivy hook and call unlink<Provider>.

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

const {unlinkEmail, unlinkGoogle, unlinkWallet} = usePrivy();
unlinkEmail();
unlinkGoogle();
unlinkWallet();

Authentication

Wallet infrastructure

External wallets

UI customization and whitelabeling

Dashboard

Social integrations

Payments and gas sponsorship

Trading integrations

Hyperliquid

Mobile

Tooling

EVM

Solana

Bitcoin

Ecosystem

Community Written Guides

​What you can customize

Authentication flows

Embedded wallets

User management

​Whitelabeling your app

​Authentication

​Wallets

​User management

​Generate SIWE message

​Sign the SIWE message

​Link with SIWE

​Usage

​Callbacks

​Generate SIWS message

​Sign the SIWS message

​Link with SIWS

​Usage

​Callbacks

​Send an OTP

​Verify the OTP

​State

​Usage

​Callbacks

​Resources

Whitelabel starter

Whitelabel demo

What you can customize

Whitelabeling your app

Authentication

Wallets

User management

Generate SIWE message

Sign the SIWE message

Link with SIWE

Usage

Callbacks

Generate SIWS message

Sign the SIWS message

Link with SIWS

Usage

Callbacks

Send an OTP

Verify the OTP

State

Usage

Callbacks

Resources