Skip to main content

Documentation Index

Fetch the complete documentation index at: https://auth0-feat-docs-5498.mintlify.app/llms.txt

Use this file to discover all available pages before exploring further.

Migrate your tenant from the legacy Auth0 Guardian phone configuration to the Unified Phone Experience using the Auth0 Terraform Provider. After migration, all multi-factor authentication (MFA) phone notifications route through a single tenant-level phone provider.
This migration requires two separate terraform apply operations.If you attempt to complete the migration with a single terraform apply command, Auth0 APIs return 403 errors because the legacy phone configuration and the Unified Phone Experience flag cannot be active at the same time.
Follow these steps to Migrate your legacy Guardian phone configuration to the Unified Phone Experince using Auth0 Terraform provider:

​
Prerequisites

​
1. Enable the Terraform auth0_phone_provider resource and remove legacy configuration

To enable the Terraform auth0_phone_provider resource and clean up legacy configuration, you need to:
  • Set the phone_consolidated_experience flag to false
  • Add the tenant-level phone provider
  • (Optional) Add the auth0_branding_phone_notification_template resource
  • Clean up the auth0_guardian phone block
  • Plan and apply

​
Set the phone_consolidated_experience flag to false

To ensure that your tenant does not route MFA phone notifications using the Unified Phone Experience, edit your auth0_tenant resource and set the phone_consolidated_experience flag to false. 
resource "auth0_tenant" "main" {
    # ... other tenant settings ...

    phone_consolidated_experience = false
}

​
Add the tenant-level phone provider

Create a tenant-level phone provider using the Terraform auth0_phone_provider resource. This provider handles delivery for all phone-based flows once the Unified Phone Experience is enabled. 
resource "auth0_phone_provider" "default" {
    name = "twilio"

    configuration {
        delivery_methods = ["text", "voice"]
        default_from     = "YOUR_DEFAULT_PHONE_NUMBER"
        sid              = var.twilio_sid
        mssid            = var.twilio_messaging_service_sid
    }

    credentials {
        auth_token = var.twilio_auth_token
    }
}
To send SMS only, set delivery_methods to ["text"].

​
(Optional) Add the auth0_branding_phone_notification_template resource

If you use enrollment_message or verification_message on the legacy Guardian phone block to customize OTP message text, you can replicate that behavior with the auth0_branding_phone_notification_template resource. 
resource "auth0_branding_phone_notification_template" "default" {
    # Refer to the Auth0 Terraform Provider docs for available template variables
}

​
Clean up the auth0_guardian phone block

Remove all legacy provider specific attributes from the phone block. After cleanup, the block should contain only enabled and message_types. Before: 
resource "auth0_guardian" "default" {
    phone {
        enabled       = true
        provider      = "twilio"
        message_types = ["sms"]

        options {
            enrollment_message   = "Your enrollment code is {{code}}"
            verification_message = "Your verification code is {{code}}"
        }

        twilio_config {
            sid                   = var.twilio_sid
            auth_token            = var.twilio_auth_token
            from                  = "YOUR_DEFAULT_PHONE_NUMBER"
            messaging_service_sid = var.twilio_messaging_service_sid
        }
    }
}
After: 
resource "auth0_guardian" "default" {
    phone {
        enabled       = true
        message_types = ["sms"]
    }
}

​
Plan and apply

Review the plan carefully before applying. You should see:
  • auth0_phone_provider.default created
  • auth0_guardian.default updated (attributes removed)
  • auth0_tenant.main updated (phone_consolidated_experience = false)
  • auth0_branding_phone_notification_template.default created (if added)
terraform plan
terraform apply

​
2. Enable the Unified Phone Experience

Once Step 1 applies cleanly, set phone_consolidated_experience to true. This activates the Unified Phone Experience and routes all MFA phone notifications through the auth0_phone_provider you configured in Step 1. 
resource "auth0_tenant" "main" {
    # ... other tenant settings ...

    phone_consolidated_experience = true
}
Apply the change: 
terraform plan
terraform apply
After this applies, Auth0 uses the Unified Phone Experience for MFA phone factor deliveries. The legacy Guardian phone API endpoints are no longer in use.

​
Troubleshooting

​
403 Forbidden errors during terraform apply

This typically means phone_consolidated_experience was already true when trying to manage legacy Guardian phone attributes. Make sure Step 1 applies with phone_consolidated_experience = false before Step 2.

​
Custom provider not delivering messages

Verify that the Action with the custom-phone-provider trigger exists and is deployed in Auth0 before applying. Terraform does not manage the Action’s existence as part of the auth0_phone_provider resource lifecycle.

​
OTP messages not arriving after migration

Confirm the auth0_phone_provider credentials are correct and that delivery_methods includes "text" for SMS. If you previously used a Messaging Service SID, ensure mssid is set on the new provider.