Update MFA phone numbers

Knowledge Articles
,
1

Last Updated March 3 2025

Overview

This article explains how to update a user’s phone number if an incorrect number is input when enrolling in Multi-Factor Authentication (MFA).

Applies To

Solution

Use the Update all authentication methods by replacing them with the given ones Management API endpoint by passing the user ID in the path with the below body:

PUT  /api/v2/users/{id}/authentication-methods
[
  {
    "type": "phone",
    "preferred_authentication_method": "sms",
    "phone_number": "+XXXXXXXXXX"
  }
]

A PUT request typically overwrites the existing data at the specified resource.

The PUT request will replace the existing data entirely, so consider the following approach:

  1. Backup the user’s Authentication Methods
  • Before sending the PUT request, retrieve the user’s current authentication methods using GET /api/v2/users/{id}/authentication-methods.
  • This ensures there is a Backup of the current data to avoid unintentional overwrites.
  1. Merge New Data with Existing Data
  • If adding a new authentication method, ensure it does not overwrite existing ones.
  • If updating an existing method, modify only the required fields while preserving the rest.
  1. Send the PUT Request
  • After merging the new and existing data into a single object, ensure the payload includes all desired authentication methods.
  1. Validation After Update
  • Perform a GET request after the PUT operation to validate that all data, including the newly updated and existing data, has been correctly preserved.
  1. Rollback or Reapply Strategy
  • If something goes wrong during the PUT operation, the data can restore the original data using the previously retrieved snapshot in step 1.