Before you start

To migrate to the Unified Phone Experience, you must:
  • Have Multi-Factor Authentication (MFA) SMS, Voice, or SMS+Voice notifications enabled and configured in your tenant, or
  • Have Passwordless SMS enabled and configured in your tenant
If you have not configured either MFA or Passwordless, read Configure Auth0’s Unified Phone Experience to start from the beginning.If you have both MFA and Passwordless integrations with different providers, you must use a Custom Phone Provider.If you utilize Phone as ID, you are automatically using Auth0’s Unified Phone Experience and no additional action is needed.
The Unified Phone Experience centralizes all your phone provider configurations in one location in your tenant. You won’t need to configure a phone provider multiple times for various phone authentication factors. To learn more about phone factors for , read SMS and voice notifications for MFA. If you already have a phone provider configured for Multi-Factor Authentication (MFA), you can migrate your configuration to the Unified Phone Experience and apply your configuration at the tenant-level.
Auth0 does not provide feedback to the end user on whether a phone message has been sent successfully with the tenant-level provider. To troubleshoot issues, review the tenant logs.

​
Update your phone provider

To use the Unified Phone Experience, you need to:
  • Verify current settings
  • Configure your provider:
    • Configure Twilio
    • Configure a custom phone provider
  • Update your phone factors and delivery methods
  • Update endpoints
  • Update Auth0 Actions triggers

​
Verify current settings

  1. To verify your current MFA settings, navigate to Auth0 Dashboard > Security > Multi-factor Auth.
  2. Select Phone Message.
  3. If you are able to use the Unified Phone Experience, a banner advises you to configure a tenant-level provider:
If you must use the legacy experience to configure your phone provider, and the toggle to use a tenant-level provider is missing, contact Auth0 Support.

​
Configure Twilio as a tenant-level provider

If you are using Twilio as your phone provider for Multi-Factor Authentication, you must add the Twilio SID and AuthToken to the Unified Phone Experience. You can copy the Twilio SID from your existing configuration, but you will need to get the value of the AuthToken from Twilio.
  1. Navigate to Branding > Phone Provider.
  2. Select and configure your provider:
    Branding > Phone Provider > Twilio
    1. Choose Twilio as your phone provider.
    2. Choose your delivery methods.
    3. Enter Twilio settings.
      Desired MFA factors must be a subset of the delivery methods you configure at the tenant-level.
  3. Save your changes.
  4. Select Send Test Message to test the tenant-level provider before using it in a production environment.
  5. Enable a tenant-level provider.
    1. For MFA, navigate to Security > Multi-factor Auth > Phone Message.
    2. Select Use Tenant-level Messaging Provider.
      If no toggle exists in your tenant, you are already using the Unified Phone experience.
  6. Save your changes.

​
Configure a custom provider with Auth0 Actions

The Unified Phone Experience uses the custom-phone-provider Actions Trigger for phone notifications rather than the send-phone-message Actions Trigger for custom phone notifications. You cannot directly migrate your send-phone-message Actions trigger to the custom-phone-provider Actions trigger because:
  • There is no 1:1 mapping between message and notification types.
  • Migrating secrets and dependencies associated with the send-phone-message Actions trigger could cause security concerns or break the tenant experience.
  • Actions can support more than one trigger and could be difficult to migrate. For example, Actions can support both the send-phone-message and post-login triggers.
  • The send-phone-message and custom-phone-provider Actions triggers support different event types:
  • You can only set one Action per custom phone provider. If you have already set an Action for a custom phone provider, you must disable it before associating it with a new Action.
As a result, you need to translate your existing send-phone-message into a new custom-phone-provider using the new contextual variables:
For a complete list of the contextual variables, read Customize Phone Templates. Review the custom phone provider example: 
const { fetch } = require('undici');
/**
* Handler to be executed while sending a phone notification
* @param {Event} event - Details about the user and the context in which they are logging in.
* @param {CustomPhoneProviderAPI} api - Methods and utilities to help change the behavior of sending a phone notification.
*/
exports.onExecuteCustomPhoneProvider = async (event, api) => {

  if (event.notification.message_type.startsWith('otp')) {
    const body = {
      from: event.notification.from,
      action: event.notification.message_type === 'otp_verify' ? 'second-factor-authenticator' : 'enrollment',
      language: event.notification.locale,
      recipient: event.notification.recipient,
      message_type: event.notification.delivery_method,
      text: event.notification.as_text,
      code: event.notification.code,
    };

    const response = await fetch(event.secrets['MY_ENDPOINT'], {
      method: 'POST',
      headers: {
        authorization: `Bearer ${event.secrets['MY_SECRET']}`,
      },
      body: JSON.stringify(body),
    });

    console.log(response.status); // 200
    console.log(await response.text()); // request's response body!
  }

  return;
};

​
Configure MFA custom-phone-provider

To continue and configure your MFA custom-phone-provider trigger:
  1. Navigate to Branding > Phone Provider.
  2. Select your provider:
    1. Choose Custom.
    2. Under Provider Configuration, add your translated send-phone-message Action code in the embedded code editor.
  3. Save your changes.
  4. Select Send Test Message to test the tenant-level provider before using it in a production environment.
  5. Navigate back to Security > Multi-factor Auth > Phone Message to enable the Use Tenant-level Messaging Provider.
  6. Save your changes.

​
Update MFA phone factors and delivery methods

If you have not enabled a tenant-level provider in the Auth0 Dashboard, you won’t be able to configure phone SMS and voice phone factors for MFA.
Unified phone MFA no tenant provider configured warning
If you want to update the current notification MFA factor(s) to a different type during the migration to the Unified Phone Experience, some configuration changes may be necessary.
Current MFA Phone factorsDesired MFA factorsTenant-level delivery methodUser action
SMSVoiceSMSUser must update tenant-level provider to allow for desired MFA phone factor
SMSVoiceSMS + VoiceNone
SMSSMS + VoiceSMSUser must update tenant-level provider to allow for desired MFA phone factor
SMSSMS + VoiceSMS + VoiceNone
VoiceSMSSMS + VoiceUser must update tenant-level provider to allow for desired MFA phone factor
VoiceSMSSMS + VoiceNone
VoiceSMS + VoiceVoiceUser must update tenant-level provider to allow for desired MFA phone factor
VoiceSMS + VoiceSMS + VoiceNone
SMS + VoiceSMSSMS + VoiceNone
SMS + VoiceVoiceSMS + VoiceNone
If you want to update the current tenant-level phone provider delivery method(s) to a different type during the migration to the Unified Phone Experience, some configuration changes may be necessary.
MFA Phone factorsCurrent tenant-level delivery methodDesired tenant-level delivery methodUser action
SMSSMSSMS + VoiceNone
SMSSMSVoiceUser must update MFA phone factors to be a subset of the delivery methods enabled for the tenant-level provider
SMSSMS + VoiceVoiceUser must update MFA phone factors to be a subset of the delivery methods enabled for the tenant-level provider
SMSSMS + VoiceSMSNone
VoiceVoiceSMSUser must update MFA phone factors to be a subset of the delivery methods enabled for the tenant-level provider
VoiceVoiceSMS + VoiceNone
VoiceSMS + VoiceSMSUser must update MFA phone factors to be a subset of the delivery methods enabled for the tenant-level provider
VoiceSMS + VoiceVoiceNone
SMS + VoiceSMS + VoiceSMSNone
SMS + VoiceSMS + VoiceVoiceNone

​
Update Guardian endpoints with Management API

The Unified Phone Experience uses specific endpoints for notifications. If you’ve been using Auth0 Guardian for push notifications and one-time passwords, you must update your configuration to use the new Phone Provider Branding endpoints. The following Guardian endpoints will no longer work with the Unified Phone Experience:
Send-phone-message Guardian endpointScope
read:guardian_factors
read:guardian_factors
update:guardian_factors
update:guardian_factors
read:guardian_factors
update:guardian_factors
Replace the Guardian endpoints with the new Phone Provider Branding endpoints and scopes:
Phone Provider Branding endpointScope
read:phone_providers
update:phone_providers
create:phone_providers
read:phone_templates
update:phone_templates
create:phone_templates
delete:phone_templates
delete:phone_providers
The following Guardian endpoints work with the Unified Phone Experience and will not need to be updated:
MFA phone factor endpointScope
read:guardian_factors
update:guardian_factors
read:guardian_factors
update:guardian_factors

​
Disable phone provider

If you configure the Unified Phone Experience and then disable it, existing integrations with your phone provider, including MFA, could break.