Updating user accounts

Email
Phone Number

To prompt users to change their email, you can use the updateEmail method from the usePrivy hook:

updateEmail: () => void

Usage

import {usePrivy} from '@privy-io/react-auth';
const {updateEmail} = usePrivy();

When invoked, the method will open the Privy modal and guide the user through updating their existing email to a new one. If a user does not already have an email account and attempts to update it, Privy will throw an error indicating such.

Example

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

function Page() {
  const {ready, authenticated, user, updateEmail} = usePrivy();

  return (
    <button onClick={updateEmail} disabled={!ready || !authenticated || !user.email}>
      Update your email
    </button>
  );
}

In the event that a user encounters an error through the flow, their existing account will be maintained.

To prompt users to change their phone number, you can use the updatePhone method from the usePrivy hook:

updatePhone: () => void

Usage

import {usePrivy} from '@privy-io/react-auth';
const {updatePhone} = usePrivy();

When invoked, the method will open the Privy modal and guide the user through updating their existing phone number to a new one. If a user does not already have a phone account and attempts to update it, Privy will throw an error indicating such.

Example

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

function Page() {
  const {ready, authenticated, user, updatePhone} = usePrivy();

  return (
    <button onClick={updatePhone} disabled={!ready || !authenticated || !user.phone}>
      Update your phone number
    </button>
  );
}

In the event that a user encounters an error through the flow, their existing account will be maintained.

Callbacks

To configure callbacks for Privy’s updateEmail and updatePhone methods, use the useUpdateAccount hook:

useUpdateAccount: ({
  onSuccess?: ({user, updateMethod, updatedAccount}) => void,
  onError?: (error, details) => void
}) => {updateEmail: () => void, updatePhone: () => void}

Usage

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

const {updateEmail, updatePhone} = useUpdateAccount({
  onSuccess: ({user, updateMethod, updatedAccount}) => {
    console.log(user, updateMethod, updatedAccount);
    // Any logic you'd like to execute if the user successfully updates an account
  },
  onError: (error, details) => {
    console.log(error, details);
    // Any logic you'd like to execute after a user exits the updateAccount flow or there is an error
  }
});

// Then call one of the update methods in your code, which will invoke these callbacks on completion

Parameters

The useUpdateAccount hook accepts an options object with the following fields:

onSuccess

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

Optional callback to run after a user successfully updates an account.

onError

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

Optional callback to run if there is an error during the update account flow, or if the user exits the flow prematurely.

Callback Details

onSuccess

If set, the onSuccess callback will execute after a user has successfully updated either their phone or email on their Privy account.Within this callback, you can access:

user

User

The user object with the user’s DID, linked accounts, and more.

updateMethod

string

A string indicating the type of update flow just executed for the authenticated user. Possible values are 'email' or 'sms'.

updatedAccount

LinkedAccountType

An object representing the account that was just updated on the authenticated user.

onError

If set, the onError callback will execute after a user initiates an update account attempt and there is an error, or if the user exits the update account flow prematurely.Within this callback, you can access:

error

string

The error code with more information about the error.

details.updateMethod

string

A string indicating the type of update account flow just attempted for the authenticated user.

Email
Phone Number

To update a user’s email, use the useUpdateEmail hook:

const {sendCode, updateEmail} = 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>

Usage

import {useUpdateEmail} from '@privy-io/expo';
const {sendCode} = useUpdateEmail();

Parameters

newEmailAddress

string

The new email address to be validated.

This will send a one-time passcode to the new email address, which the user will need to enter to verify it and confirm the update. The method returns a Promise that resolves if the code was sent successfully, and rejects otherwise.

Example

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

function UpdateEmailForm() {
  const {sendCode} = useUpdateEmail();

  const [newEmailAddress, setNewEmailAddress] = useState('');

  return (
    <View>
      <Input value={newEmailAddress} onChangeText={setNewEmailAddress} />
      <Button onPress={() => sendCode({newEmailAddress})}>Send code</Button>
    </View>
  );
}

Verify the OTP

Prompt the user for the OTP they received and verify the OTP by passing it to the updateEmail method:

updateEmail: ({newEmailAddress: string, code: string}) => Promise<User>

Usage

import {useUpdateEmail} from '@privy-io/expo';
const {updateEmail} = useUpdateEmail();

Parameters

newEmailAddress

string

The new email address to set.

code

string

The one time code received on the new email address.

Returns

user

Promise<User>

A Promise that resolves with the updated user object if the update was successful, and rejects otherwise.

Example

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

function ConfirmEmailUpdateForm() {
  const {updateEmail} = useUpdateEmail();

  const [code, setCode] = useState('');

  return (
    <View>
      <Input value={code} onChangeText={setCode} />
      <Button onPress={() => updateEmail({code, newEmailAddress})}>Confirm</Button>
    </View>
  );
}

To update a user’s phone number, use the useUpdatePhone hook:

const {sendCode, updatePhone} = useUpdatePhone();

Send an OTP

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

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

Usage

import {useUpdatePhone} from '@privy-io/expo';
const {sendCode} = useUpdatePhone();

Parameters

newPhoneNumber

string

The new phone number to be validated.

This will send a one-time passcode to the new phone number, which the user will need to enter to verify it and confirm the update. The method returns a Promise that resolves if the code was sent successfully, and rejects otherwise.

Example

import {useUpdatePhone} from '@privy-io/expo';

function UpdatePhoneForm() {
  const {sendCode} = useUpdatePhone();

  const [newPhoneNumber, setNewPhoneNumber] = useState('');

  return (
    <View>
      <Input value={newPhoneNumber} onChangeText={setNewPhoneNumber} />
      <Button onPress={() => sendCode({newPhoneNumber})}>Send code</Button>
    </View>
  );
}

Verify the OTP

Prompt the user for the OTP they received and verify the OTP by passing it to the updatePhone method:

updatePhone: ({newPhoneNumber: string, code: string}) => Promise<User>

Usage

import {useUpdatePhone} from '@privy-io/expo';
const {updatePhone} = useUpdatePhone();

Parameters

newPhoneNumber

string

The new phone number to set.

code

string

The one time code received on the new phone number.

Returns

user

Promise<User>

A Promise that resolves with the updated user object if the update was successful, and rejects otherwise.

Example

import {useUpdatePhone} from '@privy-io/expo';

function ConfirmPhoneUpdateForm() {
  const {updatePhone} = useUpdatePhone();

  const [code, setCode] = useState('');

  return (
    <View>
      <Input value={code} onChangeText={setCode} />
      <Button onPress={() => updatePhone({code, newPhoneNumber})}>Confirm</Button>
    </View>
  );
}

Email
Phone Number

To update a user’s email, use the privy.email.updateWithCode method:

updateWithCode(_ code: String, sentTo email: String) async throws

Send an OTP

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

sendCode(to email: String) async throws

Usage

try await privy.email.sendCode(to: "[email protected]")
// successfully sent code to user's new email

Parameters

to email

string

The new email address to be validated.

This will send a one-time passcode to the new email address, which the user will need to enter to verify it and confirm the update.

Verify the OTP

Prompt the user for the OTP they received and verify the OTP by passing it to the updateWithCode method:

updateWithCode(_ code: String, sentTo email: String) async throws

Usage

try await privy.email.updateWithCode("123456", sentTo: "[email protected]")

Parameters

_ code

string

The one time code received on the new email address.

sentTo email

string

The new email address to set.

To update a user’s phone number, use the privy.sms.updateWithCode method:

updateWithCode(_ code: String, sentTo phoneNumber: String) async throws

Send an OTP

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

sendCode(to phoneNumber: String) async throws

Usage

try await privy.sms.sendCode(to: "+1234567890")
// successfully sent code to user's new phone number

Parameters

to phoneNumber

string

The new phone number to be validated.

This will send a one-time passcode to the new phone number, which the user will need to enter to verify it and confirm the update.

Verify the OTP

Prompt the user for the OTP they received and verify the OTP by passing it to the updateWithCode method:

updateWithCode(_ code: String, sentTo phoneNumber: String) async throws

Usage

try await privy.sms.updateWithCode("123456", sentTo: "+1234567890")

Parameters

_ code

string

The one time code received on the new phone number.

sentTo phoneNumber

string

The new phone number to set.

Email
Phone Number

To update a user’s email, use the privy.email.updateWithCode method:

suspend fun updateWithCode(code: String, email: String): Result<Unit>

Send an OTP

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

suspend fun sendCode(email: String): Result<Unit>

Usage

privy.email.sendCode(email = "[email protected]").fold(
    onSuccess = {
        // Successfully sent code to user's new email address
    },
    onFailure = { error ->
        // Handle error
    }
)

Parameters

email

String

The new email address to be validated.

This will send a one-time passcode to the new email address, which the user will need to enter to verify it and confirm the update.

Verify the OTP

Prompt the user for the OTP they received and verify the OTP by passing it to the updateWithCode method:

suspend fun updateWithCode(code: String, email: String): Result<Unit>

Usage

privy.email.updateWithCode(code = "123456", email = "[email protected]").fold(
    onSuccess = {
        // Email address successfully updated
    },
    onFailure = { error ->
        // Handle error
    }
)

Parameters

code

String

The one time code received on the new email address.

email

String

The new email address to set.

To update a user’s phone number, use the privy.sms.updateWithCode method:

suspend fun updateWithCode(code: String, phoneNumber: String): Result<Unit>

Send an OTP

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

suspend fun sendCode(phoneNumber: String): Result<Unit>

Usage

privy.sms.sendCode(phoneNumber = "+15551234567").fold(
    onSuccess = {
        // Successfully sent code to user's new phone number
    },
    onFailure = { error ->
        // Handle error
    }
)

Parameters

phoneNumber

String

The new phone number to be validated.

This will send a one-time passcode to the new phone number, which the user will need to enter to verify it and confirm the update.

Verify the OTP

Prompt the user for the OTP they received and verify the OTP by passing it to the updateWithCode method:

suspend fun updateWithCode(code: String, phoneNumber: String): Result<Unit>

Usage

privy.sms.updateWithCode(code = "123456", phoneNumber = "+15551234567").fold(
    onSuccess = {
        // Phone number successfully updated
    },
    onFailure = { error ->
        // Handle error
    }
)

Parameters

code

String

The one time code received on the new phone number.

phoneNumber

String

The new phone number to set.

Migrating users to Privy

Users

Managing users

Webhooks

​Usage

​Example

​Usage

​Example

​Callbacks

​Usage

​Parameters

​Callback Details

​onSuccess

​onError

​Send an OTP

​Usage

​Parameters

​Example

​Verify the OTP

​Usage

​Parameters

​Returns

​Example

​Send an OTP

​Usage

​Parameters

​Example

​Verify the OTP

​Usage

​Parameters

​Returns

​Example

​Send an OTP

​Usage

​Parameters

​Verify the OTP

​Usage

​Parameters

​Send an OTP

​Usage

​Parameters

​Verify the OTP

​Usage

​Parameters

​Send an OTP

​Usage

​Parameters

​Verify the OTP

​Usage

​Parameters

​Send an OTP

​Usage

​Parameters

​Verify the OTP

​Usage

​Parameters

Usage

Example

Usage

Example

Callbacks

Usage

Parameters

Callback Details

onSuccess

onError

Send an OTP

Usage

Parameters

Example

Verify the OTP

Usage

Parameters

Returns

Example

Send an OTP

Usage

Parameters

Example

Verify the OTP

Usage

Parameters

Returns

Example

Send an OTP

Usage

Parameters

Verify the OTP

Usage

Parameters

Send an OTP

Usage

Parameters

Verify the OTP

Usage

Parameters

Send an OTP

Usage

Parameters

Verify the OTP

Usage

Parameters

Send an OTP

Usage

Parameters

Verify the OTP

Usage

Parameters