Unlinking accounts from users

Developers can use Privy to prompt users to unlink their linked accounts (such as a wallet or Discord profile) at any point in their user journey. This might be useful whenever the user has either created a new external account (such as a new Twitter profile or email address) and want to remove the old linked account from their user.

The React SDK supports unlinking all supported account types via our modal-guided link methods. To prompt a user to unlink an account, use the respective method from the usePrivy hook:

Method	Description
`unlinkEmail`	unlinks email address
`unlinkPhone`	unlinks phone number
`unlinkWallet`	unlinks external wallet
`unlinkGoogle`	unlinks Google account
`unlinkApple`	unlinks Apple account
`unlinkTwitter`	unlinks Twitter account
`unlinkDiscord`	unlinks Discord account
`unlinkGithub`	unlinks Github account
`unlinklinkedIn`	unlinks LinkedIn account
`unlinkTikTok`	unlinks TikTok account
`unlinkSpotify`	unlinks Spotify account
`unlinkInstagram`	unlinks Instagram account
`unlinkTelegram`	unlinks Telegram account
`unlinkFarcaster`	unlinks Farcaster account
`unlinkPasskey`	unlinks passkey

Users are only permitted to unlink an account so long as they have at least one more linked account.

Below is an example button for prompting a user to unlink certain linked accounts:

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

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

return (
<div className="unlink-options">
<button onClick={unlinkEmail}>Unlink Email to user</button>
<button onClick={unlinkGoogle}>Unlink Google account to user</button>
<button onClick={unlinkWallet}>Unlink Wallet to user</button>
</div>
);
}

To prompt a user to unlink an account, use the respective functions and hooks:

Account type	Description	Hook to invoke
`Email`	Unlinks email address	`useUnlinkEmail`
`Wallet`	Unlinks external wallet	`useUnlinkWallet`
`Google`	Unlinks Google account	`useUnlinkOAuth`
`Apple`	Unlinks Apple account	`useUnlinkOAuth`
`Twitter`	Unlinks Twitter account	`useUnlinkOAuth`
`Discord`	Unlinks Discord account	`useUnlinkOAuth`
`Github`	Unlinks Github account	`useUnlinkOAuth`
`LinkedIn`	Unlinks LinkedIn account	`useUnlinkOAuth`
`TikTok`	Unlinks TikTok account	`useUnlinkOAuth`
`Spotify`	Unlinks Spotify account	`useUnlinkOAuth`
`Instagram`	Unlinks Instagram account	`useUnlinkOAuth`
`Farcaster`	Unlinks Farcaster account	`useUnlinkFarcaster`

Users are only permitted to unlink an account so long as they have at least one more linked account.

Email
Wallet
OAuth
Farcaster

Usage

import {useUnlinkEmail} from '@privy-io/expo';
const {unlinkEmail} = useUnlinkEmail();
await unlinkEmail({ email: '[email protected]' });

Parameters

string

required

The email address to unlink from the current user.

Callbacks

You can optionally register an onSuccess or onError callback on the useUnlinkEmail hook.

import {useUnlinkEmail} from '@privy-io/expo';
const {unlinkEmail} = useUnlinkEmail({
  onSuccess: (user) => {
    console.log('Email unlinked', user);
  },
  onError: (err) => console.error(err),
});

onSuccess

(user: User) => void

Optional callback to run after a user successfully unlinks an email address.

onError

(err: string) => void

Optional callback to run after there is an error during email unlinking.

Usage

import {useUnlinkWallet} from '@privy-io/expo';
const {unlinkWallet} = useUnlinkWallet();
await unlinkWallet({ address: 'wallet_address' });

Parameters

address

string

required

The wallet address to unlink from the current user.

Callbacks

You can optionally register an onSuccess or onError callback on the useUnlinkWallet hook.

import {useUnlinkWallet} from '@privy-io/expo';
const {unlinkWallet} = useUnlinkWallet({
  onSuccess: (user, isNewUser) => {
    console.log('Wallet unlinked', user, isNewUser);
  },
  onError: (err) => console.error(err),
});

onSuccess

(user: User, isNewUser: boolean) => void

Optional callback to run after a user successfully unlinks a wallet.

onError

(err: string) => void

Optional callback to run after there is an error during wallet unlinking.

Usage

import {useUnlinkOAuth} from '@privy-io/expo';
const {unlinkOAuth} = useUnlinkOAuth();
await unlinkOAuth({ provider: 'google', subject: 'subject_identifier' });

Parameters

provider

required

The OAuth provider for the account to unlink.

subject

string

required

The provider-specific subject (“sub” claim) that uniquely identifies the user for the selected OAuth provider.

Usage

import {useUnlinkFarcaster} from '@privy-io/expo';
const {unlinkFarcaster} = useUnlinkFarcaster();
await unlinkFarcaster({ fid: 123 });

Parameters

fid

number

required

The Farcaster ID to unlink from the current user.

Callbacks

You can optionally register an onSuccess or onError callback on the useUnlinkFarcaster hook.

import {useUnlinkFarcaster} from '@privy-io/expo';
const {unlinkFarcaster} = useUnlinkFarcaster({
  onSuccess: (user) => console.log('Farcaster unlinked', user),
  onError: (err) => console.error(err),
});

onSuccess

(user: User) => void

Optional callback to run after a user successfully unlinks a Farcaster account.

onError

(err: string) => void

Optional callback to run after there is an error during Farcaster unlinking.

Users are only permitted to unlink an account so long as they have at least one more linked account.

Solana Wallet
Passkey

Use the following method from the siws handler to unlink a Solana wallet:

func unlink(address: String) async throws

Usage

do {
    // unlink Solana wallet with address
    try await privy.siws.unlink(address: address)

    // successfully unlinked Solana wallet
} catch {
    // error unlinking Solana wallet
}

Use the following method from the passkey handler to unlink a user’s passkey:

func unlink(credentialId: String) async throws

Usage

do {
    // unlink passkey with credential id
    try await privy.passkey.unlink(credentialId: credentialId)

    // successfully unlinked passkey
} catch {
    // error unlinking passkey
}

Users are only permitted to unlink an account so long as they have at least one more linked account.

Email
Phone
Ethereum wallet
Solana wallet
Passkey

Use the following method from the email handler to unlink an email address:

public suspend fun unlink(email: String): Result<PrivyUser>

Returns

Result<PrivyUser>

A result type encapsulating the PrivyUser on success.

Usage

val unlinkResult: Result<PrivyUser> = privy.email.unlink(email = "[email protected]")

unlinkResult.fold(
    onSuccess = { updatedUser ->
        // Email successfully unlinked
        // updatedUser contains the updated user object with the email removed
    },
    onFailure = {
        println("Error unlinking email: ${it.message}")
    }
)

Use the following method from the sms handler to unlink a phone number:

public suspend fun unlink(phoneNumber: String): Result<PrivyUser>

Returns

Result<PrivyUser>

A result type encapsulating the PrivyUser on success.

Usage

val unlinkResult: Result<PrivyUser> = privy.sms.unlink(phoneNumber = "+1234567890")

unlinkResult.fold(
    onSuccess = { updatedUser ->
        // Phone number successfully unlinked
        // updatedUser contains the updated user object with the phone number removed
    },
    onFailure = {
        println("Error unlinking SMS: ${it.message}")
    }
)

Use the following method from the siwe handler to unlink an Ethereum wallet:

public suspend fun unlink(address: String): Result<PrivyUser>

Returns

Result<PrivyUser>

A result type encapsulating the PrivyUser on success.

Usage

val unlinkResult: Result<PrivyUser> = privy.siwe.unlink(address = "wallet_address")

unlinkResult.fold(
    onSuccess = { updatedUser ->
        // Wallet successfully unlinked
        // updatedUser contains the updated user object with the wallet removed
    },
    onFailure = {
        println("Error unlinking wallet: ${it.message}")
    }
)

Use the following method from the siws handler to unlink a Solana wallet:

public suspend fun unlink(address: String): Result<PrivyUser>

Returns

Result<PrivyUser>

A result type encapsulating the PrivyUser on success.

Usage

val unlinkResult: Result<PrivyUser> = privy.siws.unlink(address = "wallet_address")

unlinkResult.fold(
    onSuccess = { updatedUser ->
        // Wallet successfully unlinked
        // updatedUser contains the updated user object with the wallet removed
    },
    onFailure = {
        println("Error unlinking wallet: ${it.message}")
    }
)

Use the following method from the passkey handler to unlink a passkey:

public suspend fun unlink(credentialId: String): Result<PrivyUser>

Returns

Result<PrivyUser>

A result type encapsulating the PrivyUser on success.

Usage

val unlinkResult: Result<PrivyUser> = privy.passkey.unlink(credentialId = "credential_id")

unlinkResult.fold(
    onSuccess = { updatedUser ->
        // Passkey successfully unlinked
        // updatedUser contains the updated user object with the passkey removed
    },
    onFailure = {
        println("Error unlinking passkey: ${it.message}")
    }
)

Users are only permitted to unlink an account so long as they have at least one more linked account.

Unlink Solana Wallet
Unlink Passkey

Use the following method from the siws handler to unlink a Solana wallet:

Future<Result<void>> unlink({required String address})

Parameters

address

String

required

The Solana wallet address to unlink from the user.

Returns

Result<void>

A Result object that indicates whether the operation was successful.

Usage

final unlinkResult = await privy.siws.unlink(address: "wallet_address");

unlinkResult.fold(
  onSuccess: (_) {
    // Wallet successfully unlinked
  },
  onFailure: (error) {
    print("Error unlinking wallet: ${error.message}");
  },
);

Use the following method from the passkey handler to unlink a passkey:

Future<Result<void>> unlink({required String credentialId})

Parameters

credentialId

String

required

The credential ID of the passkey to unlink.

Returns

Result<void>

A Result object that indicates whether the operation was successful.

Usage

final unlinkResult = await privy.passkey.unlink(credentialId: "credential_id");

unlinkResult.fold(
  onSuccess: (_) {
    // Passkey successfully unlinked
  },
  onFailure: (error) {
    print("Error unlinking passkey: ${error.message}");
  },
);

Make a POST request to:

https://auth.privy.io/api/v1/apps/<privy-app-id>/users/unlink

Replace <privy-app-id> with your Privy app ID and pass in the following parameters:

Parameter	Type	Description
`user_id`	`string`	Privy DID of the user
`type`	`string`	Linked account type (see supported types below)
`handle`	`string`	The identifier for the account (e.g., email address, wallet address)
`provider`	`string`	(Only required for cross app unlinking) The cross app provider id, prefixed with `'privy:'`

Supported Account Types

The following account types can be unlinked via the API:

email - Email accounts
phone - Phone number accounts
wallet - Externally connected wallets (Ethereum or Solana)
smart_wallet - Smart contract wallets
farcaster - Farcaster accounts
telegram - Telegram accounts
cross_app - Cross app accounts
OAuth providers:
- google_oauth
- discord_oauth
- twitter_oauth
- github_oauth
- linkedin_oauth
- apple_oauth
- spotify_oauth
- instagram_oauth
- tiktok_oauth

The API does not support unlinking passkey, custom_auth, cross_app, or guest account types.

Example Requests

curl --request POST "https://auth.privy.io/api/v1/apps/<privy-app-id>/users/unlink" \
-u "<your-privy-app-id>:<your-privy-app-secret>" \
-H "privy-app-id: <your-privy-app-id>" \
-H 'Content-Type: application/json' \
-d '{
  "user_id": "<user-did>",
  "type": "email",
  "handle": "[email protected]"
}'

Response

If the unlinking is successful, the API will return a 200 status code.If there’s no account associated with the Privy DID that matches the type and handle, the API will return a 400 status code.

To unlink via the dashboard:

Navigate to the Users page
Select the user
Click the button beside the account you want to unlink
Click Unlink account

The unlink option won’t appear if unlinking is not available for the account.

Unlinking an account in the Privy Dashboard

Migrating users to Privy

Users

Managing users

Webhooks

Unlinking accounts from users

Usage

Parameters

Callbacks

Usage

Parameters

Callbacks

Usage

Parameters

Usage

Parameters

Callbacks

Usage

Usage

Returns

Usage

Returns

Usage

Returns

Usage

Returns

Usage

Returns

Usage

Parameters

Returns

Usage

Parameters

Returns

Usage

Supported Account Types

Example Requests

Response

Migrating users to Privy

Users

Managing users

Webhooks

​Usage

​Parameters

​Callbacks

​Usage

​Parameters

​Callbacks

​Usage

​Parameters

​Usage

​Parameters

​Callbacks

​Usage

​Usage

​Returns

​Usage

​Returns

​Usage

​Returns

​Usage

​Returns

​Usage

​Returns

​Usage

​Parameters

​Returns

​Usage

​Parameters

​Returns

​Usage

​Supported Account Types

​Example Requests

​Response

Usage

Parameters

Callbacks

Usage

Parameters

Callbacks

Usage

Parameters

Usage

Parameters

Callbacks

Usage

Usage

Returns

Usage

Returns

Usage

Returns

Usage

Returns

Usage

Returns

Usage

Parameters

Returns

Usage

Parameters

Returns

Usage

Supported Account Types

Example Requests

Response