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
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
- 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
- To verify your current MFA settings, navigate to Auth0 Dashboard > Security > Multi-factor Auth .
- Select Phone Message .
-
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
- Navigate to Branding > Phone Provider .
-
Select and configure your provider:

- Choose Twilio as your phone provider.
- Choose your delivery methods.
-
Enter Twilio settings.
Desired MFA factors must be a subset of the delivery methods you configure at the tenant-level.
- Save your changes.
- Select Send Test Message to test the tenant-level provider before using it in a production environment.
-
Enable a tenant-level provider.
- For MFA, navigate to Security > Multi-factor Auth > Phone Message .
- Select Use Tenant-level Messaging Provider .
- Save your changes.
Configure a custom provider with Auth0 Actions
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-messageandpost-logintriggers. -
The
send-phone-messageandcustom-phone-providerActions triggers support different event types:send-phone-messagesupports the SMS and Voice message types. To learn more, read Action triggers: send-phone-message Event Object.custom-phone-providersupports theotp_verify,otp_enroll,blocked_account,change_password, andpassword_breachnotification types. To learn more, read Actions triggers: custom-phone-provider Event Object.
- 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.
send-phone-message into a new custom-phone-provider using the new contextual variables:
Core payload
Core payload
send-phone-message context object | custom-phone-provider context object | Status |
|---|---|---|
text | notification.as_text and notification.as_voice | Updated |
message_type | notification.message_type
| Updated |
action | notification.delivery_method | Updated |
language | notification.locale | Updated |
code | notification.code | Updated |
recipient | notification.recipient | Updated |
Request data
Request data
send-phone-message context object | Tenant-level provider context object | Status |
|---|---|---|
ip | ip | Unchanged |
user_agent | user_agent | Unchanged |
language | language | Updated |
method | method optional | Updated |
hostname | hostname optional | Updated |
geoip | geoip | Updated |
Tenant data
Tenant data
send-phone-message context object | Tenant-level provider context object | Status |
|---|---|---|
tenant.id | tenant | Updated |
| N/A | tenant.home_url | New |
| N/A | tenant.logo_url | New |
| N/A | tenant.support_email | New |
| N/A | tenant.support_url | New |
Application data
Application data
send-phone-message context object | Tenant-level provider context object | Status |
|---|---|---|
client.client_metadata | client.metadata | Updated |
client.client_id | client.client_id | Unchanged |
client.name | client.name | Unchanged |
User data
User data
send-phone-message context object | Tenant-level provider context object | Status |
|---|---|---|
user.user_id | user.user_id | Unchanged |
user.name | user.name | Unchanged |
user.email | user.email | Unchanged |
user.app_metadata | user.app_metadata | Unchanged |
user.user_metadata | user.user_metadata | Unchanged |
user.email_verified | user.email_verified | Unchanged |
user.phone_number | user.phone_number | Unchanged |
user.phone_verified | user.phone_verified | Unchanged |
user.picture | user.picture | Unchanged |
user.created_at | user.created_at | Unchanged |
user.updated_at | user.updated_at | Unchanged |
user.multifactor | user.multifactor | Unchanged |
user.identities | N/A | Removed |
user.family_name | user.family_name | Unchanged |
user.given_name | user.given_name | Unchanged |
user.nickname | user.nickname | Unchanged |
user.username | user.username | Unchanged |
| N/A | user.login_count | New |
Configure MFA custom-phone-provider
custom-phone-provider trigger:
- Navigate to Branding > Phone Provider .
-
Select your provider:
- Choose Custom .
- Under Provider Configuration , add your translated
send-phone-messageAction code in the embedded code editor.
- Save your changes.
- Select Send Test Message to test the tenant-level provider before using it in a production environment.
- Navigate back to Security > Multi-factor Auth > Phone Message to enable the Use Tenant-level Messaging Provider .
- Save your changes.
Update MFA phone factors and delivery methods
| Current MFA Phone factors | Desired MFA factors | Tenant-level delivery method | User action |
|---|---|---|---|
| SMS | Voice | SMS | User must update tenant-level provider to allow for desired MFA phone factor |
| SMS | Voice | SMS + Voice | None |
| SMS | SMS + Voice | SMS | User must update tenant-level provider to allow for desired MFA phone factor |
| SMS | SMS + Voice | SMS + Voice | None |
| Voice | SMS | SMS + Voice | User must update tenant-level provider to allow for desired MFA phone factor |
| Voice | SMS | SMS + Voice | None |
| Voice | SMS + Voice | Voice | User must update tenant-level provider to allow for desired MFA phone factor |
| Voice | SMS + Voice | SMS + Voice | None |
| SMS + Voice | SMS | SMS + Voice | None |
| SMS + Voice | Voice | SMS + Voice | None |
| MFA Phone factors | Current tenant-level delivery method | Desired tenant-level delivery method | User action |
|---|---|---|---|
| SMS | SMS | SMS + Voice | None |
| SMS | SMS | Voice | User must update MFA phone factors to be a subset of the delivery methods enabled for the tenant-level provider |
| SMS | SMS + Voice | Voice | User must update MFA phone factors to be a subset of the delivery methods enabled for the tenant-level provider |
| SMS | SMS + Voice | SMS | None |
| Voice | Voice | SMS | User must update MFA phone factors to be a subset of the delivery methods enabled for the tenant-level provider |
| Voice | Voice | SMS + Voice | None |
| Voice | SMS + Voice | SMS | User must update MFA phone factors to be a subset of the delivery methods enabled for the tenant-level provider |
| Voice | SMS + Voice | Voice | None |
| SMS + Voice | SMS + Voice | SMS | None |
| SMS + Voice | SMS + Voice | Voice | None |
Update Guardian endpoints with Management API
| Send-phone-message Guardian endpoint | Scope |
|---|---|
read:guardian_factors | |
read:guardian_factors | |
update:guardian_factors | |
update:guardian_factors | |
read:guardian_factors | |
update:guardian_factors |
| Phone Provider Branding endpoint | Scope |
|---|---|
read:phone_providers | |
update:phone_providers | |
create:phone_providers | |
read:phone_templates | |
update:phone_templates | |
create:phone_templates | |
delete:phone_templates | |
delete:phone_providers |
| MFA phone factor endpoint | Scope |
|---|---|
read:guardian_factors | |
update:guardian_factors | |
read:guardian_factors | |
update:guardian_factors |
Disable phone provider

