Is there a way to register or manage mobile number for SMS MFA using APIs

Get Help
,
1

We turned off user signup process in Auth0 and register our users using management API. This is really a business requirement as app is restricited from self-serve signup.

And mobile number is not a unique value within our app, a user can hold multiple accounts so this is limiting us from using default phone_number user attribute for various functions.

We are getting a change-password ticket for the user and redirecting the user to the Auth0 magic link so user sets their first password after they go through our app signup flow. As we can’t use phone_number attribute on user profile is there a way to directly register the user for SMS MFA with the phone number that we have for the user. This is a verified phone number so we don’t want to ask user to go through the SMS verification again.

Also when user updates their mobile number in our app, we want to update the mobile number directly on the register SMS MFA option in Auth0 using a Management API call

3

Hi @karuissobusy

Thank you for reaching out to us!

I understand that you are looking to directly enroll users in Auth0 SMS Multi-Factor Authentication using the Management API with a pre-verified phone number from your app, without requiring users to re-verify and also, how to update that phone number later when users change it in your app.

Because you already have the verified phone number from your application, you can use the Management API to directly create the SMS MFA factor. Authentication methods created via the Management API are automatically confirmed and available immediately, which completely bypasses the need for the user to go through Auth0’s SMS verification step.

Recommended approach

Here is how to implement both the initial enrollment and the subsequent updates:

1. Directly Register the User for SMS MFA

To directly enroll a user with their verified phone number, you will make a POST request to the Create Authentication Method endpoint.

Endpoint: POST /api/v2/users/{id}/authentication-methods
Required Scope: create:authentication_methods

Payload:

{
  "type": "phone",
  "phone_number": "+1XXXXXXXXXX", 
  "preferred_authentication_method": "sms"
}

(Note: Ensure the phone number is formatted in E.164 format, including the country code).

Once this request is successful, the user is immediately enrolled in SMS MFA with that number, and Auth0 will not challenge them to verify it.

2. Update the SMS MFA Phone Number

When a user updates their mobile number in your app, you will also need to update this factor in Auth0. While Auth0 does have a PUT /api/v2/users/{id}/authentication-methods endpoint, we do heavily warn against using it because it will completely overwrite all existing MFA factors (e.g., if the user also set up an Authenticator App).

To safely update only the SMS factor without affecting other factors, we recommend a Delete & Create approach:

Step A: Retrieve existing methods
Make a GET /api/v2/users/{id}/authentication-methods request (Requires read:authentication_methods scope). Find the ID of the existing phone authentication method (it usually starts with sms|).

Step B: Delete the old SMS factor
Make a DELETE /api/v2/users/{id}/authentication-methods request to remove the outdated number.

Step C: Create the new SMS factor
Make the exact same POST request from Step 1 using the newly verified phone number.

Key Takeaway: By utilizing the Management API’s /authentication-methods endpoint, Auth0 implicitly trusts the factor you are supplying. Just ensure your backend securely manages the API token with the read:authentication_methods, create:authentication_methods, and delete:authentication_methods scopes.

Hope this helped resolve the issue!

Have a great one,
Gerald