Add a new phone authentication method for a user. A user may only have one phone of each type, captured in the phoneType property. This means, for example, adding a mobile phone to a user with a pre-existing mobile phone fails. Additionally, a user must always have a mobile phone before adding an alternateMobile phone.
Adding a phone number makes it available for use in both Azure multi-factor authentication (MFA) and self-service password reset (SSPR), if enabled.
Additionally, if a user is enabled by policy to use SMS sign-in and a mobile number is added, the system attempts to register the number for use in that system.
Choose the permission or permissions marked as least privileged for this API. Use a higher privileged permission or permissions only if your app requires it. For details about delegated and application permissions, see Permission types. To learn more about these permissions, see the permissions reference.
Permission type
Least privileged permissions
Higher privileged permissions
Delegated (work or school account)
UserAuthenticationMethod.ReadWrite.All
UserAuthenticationMethod.ReadWrite
Delegated (personal Microsoft account)
Not supported.
Not supported.
Application
UserAuthenticationMethod.ReadWrite.All
Not available.
For delegated scenarios, the administrator needs at least the Authentication Administrator or Privileged Authentication AdministratorMicrosoft Entra role.
Users can't add a phone authentication method to their own account.
HTTP request
Add a phone authentication method to another user's account.
POST /users/{id | userPrincipalName}/authentication/phoneMethods
In the request body, supply a JSON representation of a phoneAuthenticationMethod object. The JSON must include phoneNumber and phoneType, but not smsSignInState (which is read-only).
Property
Type
Description
phoneNumber
String
The phone number to text or call for authentication. Phone numbers use the format +{country code} {number}x{extension}, with extension optional. For example, +1 5555551234 or +1 5555551234x123 are valid. Numbers are rejected when creating or updating if they don't match the required format.
phoneType
String
Possible values are: mobile, alternateMobile, and office.
Response
If successful, this method returns a 201 Created response code and a new phoneAuthenticationMethod object in the response body.
// Code snippets are only available for the latest version. Current version is 5.x
// Dependencies
using Microsoft.Graph.Models;
var requestBody = new PhoneAuthenticationMethod
{
PhoneNumber = "+1 2065555555",
PhoneType = AuthenticationPhoneType.Mobile,
};
// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Users["{user-id}"].Authentication.PhoneMethods.PostAsync(requestBody);
// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
mgc users authentication phone-methods create --user-id {user-id} --body '{\
"phoneNumber": "+1 2065555555",\
"phoneType": "mobile"\
}\
'
// Code snippets are only available for the latest version. Current version is 6.x
GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);
PhoneAuthenticationMethod phoneAuthenticationMethod = new PhoneAuthenticationMethod();
phoneAuthenticationMethod.setPhoneNumber("+1 2065555555");
phoneAuthenticationMethod.setPhoneType(AuthenticationPhoneType.Mobile);
PhoneAuthenticationMethod result = graphClient.users().byUserId("{user-id}").authentication().phoneMethods().post(phoneAuthenticationMethod);