Whitelabel

Privy enables complete control over user management flows, so you can match every user action to your app’s brand and experience. Build your own UI for linking and unlinking accounts, managing user profiles, and more, while Privy handles the backend logic securely.

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 an additional OAuth account

To link additional OAuth providers that are not natively supported by Privy, use the linkOAuth method from the useLinkAccount hook. For built-in providers like Google or Twitter, use the dedicated methods (e.g., linkGoogle, linkTwitter).

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

const {linkOAuth} = useLinkAccount();
linkOAuth({provider: 'custom:twitch'});

Parameters

The linkOAuth method accepts an object with the following fields:

provider · string · required

The additional OAuth provider to link, in the format 'custom:<provider-name>' (e.g., 'custom:twitch').

Usage

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

function LinkTwitchButton() {
  const {linkOAuth} = useLinkAccount({
    onSuccess: ({user, linkMethod, linkedAccount}) => {
      console.log('Linked account:', linkedAccount);
    },
    onError: (error) => {
      console.error('Failed to link account:', error);
    }
  });

  return (
    <button onClick={() => linkOAuth({provider: 'custom:twitch'})}>Link Twitch account</button>
  );
}

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)

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);
  }
});

Solana (SIWS)

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.

Linking a custom JWT account

To link a custom JWT account to an existing user, use the useLinkJwtAccount hook. This is useful for integrating with external authentication systems that issue JWTs.

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

const {linkWithCustomJwt, state} = useLinkJwtAccount();

Link with custom JWT

linkWithCustomJwt(jwt: string) => Promise<{user: User}>

jwt · string · required

The JWT token from your external authentication system to link to the user’s account.

State

The state property tracks the current state of the JWT linking flow:

Status	Description
'initial'	The flow has not started
'loading'	The JWT is being verified and linked
'not-enabled'	Custom JWT auth is not enabled for this app
'done'	The account was linked successfully
'error'	An error occurred

Callbacks

You can optionally pass callbacks into useLinkJwtAccount:

const {linkWithCustomJwt, state} = useLinkJwtAccount({
  onSuccess: ({user, linkMethod, linkedAccount}) => {
    console.log('JWT account linked successfully', linkedAccount);
  },
  onError: (error) => {
    console.error('Failed to link JWT account', error);
  }
});

Usage

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

function LinkJwtAccountButton() {
  const {linkWithCustomJwt, state} = useLinkJwtAccount({
    onSuccess: ({user, linkedAccount}) => {
      console.log('Account linked:', linkedAccount);
    },
    onError: (error) => {
      console.error('Link failed:', error);
    }
  });

  const handleLink = async () => {
    const jwt = await getJwtFromExternalAuth();
    await linkWithCustomJwt(jwt);
  };

  return (
    <button onClick={handleLink} disabled={state.status === 'loading'}>
      Link External Account
    </button>
  );
}

Custom JWT authentication must be enabled in your Privy Dashboard before using this hook. See the JWT-based authentication documentation for setup instructions.

Unlinking an account

To whitelabel unlinking an account, use the dedicated unlink hooks from @privy-io/react-auth:

import {useUnlinkEmail, useUnlinkWallet, useUnlinkOAuth} from '@privy-io/react-auth';

const {unlink: unlinkEmail} = useUnlinkEmail();
const {unlink: unlinkWallet} = useUnlinkWallet();
const {unlink: unlinkOAuth} = useUnlinkOAuth();

// Unlink by passing the relevant identifier
unlinkEmail({address: '[e-mail]'});
unlinkOAuth({provider: 'google', subject: 'google-subject-id'});
unlinkWallet({address: '0x...'});

See the unlinking accounts guide for the full list of available hooks and parameters.

Unlinking an OAuth account

To unlink any OAuth provider, including built-in providers (e.g., 'google', 'twitter') and additional OAuth providers (e.g., 'custom:twitch'), use the useUnlinkOAuth hook.

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

const {unlink: unlinkOAuth} = useUnlinkOAuth();
unlinkOAuth({provider: 'custom:twitch', subject: '12345'});

Parameters

The unlink method from useUnlinkOAuth accepts an object with the following fields:

provider · string · required

The OAuth provider to unlink. Use a built-in provider (e.g., 'google', 'twitter') or a custom provider in the format 'custom:<provider-name>' (e.g., 'custom:twitch').

subject · string · required

The provider-specific subject identifier that uniquely identifies the user for the selected OAuth provider. This can be found in the linked account’s subject field.

Usage

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

function UnlinkTwitchButton() {
  const {user} = usePrivy();
  const {unlink: unlinkOAuth} = useUnlinkOAuth();

  // Find the custom OAuth account to unlink
  const twitchAccount = user?.linkedAccounts?.find((account) => account.type === 'custom:twitch');

  const handleUnlink = () => {
    if (twitchAccount) {
      unlinkOAuth({
        provider: 'custom:twitch',
        subject: twitchAccount.subject
      });
    }
  };

  return (
    <button onClick={handleUnlink} disabled={!twitchAccount}>
      Unlink Twitch account
    </button>
  );
}