Skip to main content
Migrate your tenant from the legacy Auth0 Guardian phone configuration to the Unified Phone Experience (UPE) using the Auth0 Terraform Provider. After migration, all multi-factor authentication (MFA) phone notifications route through a single tenant-level phone provider.

​
Prerequisites

Before you begin migration, you need:

​
Enable the phone provider resource and remove legacy configuration

To enable the Terraform auth0_phone_provider resource and clean up legacy configuration:

​
Set the consolidated experience flag

To ensure your Auth0 tenant enables UPE and routes all MFA phone notifications through the unified provider, edit your auth0_tenant resource and set the phone_consolidated_experience flag to true. 
resource "auth0_tenant" "main" {
    # ... other tenant settings ...

    phone_consolidated_experience = true
}

​
Add the tenant-level phone provider

Create a tenant-level phone provider using the Terraform auth0_phone_provider resource to handle delivery for all phone-based flows under the Unified Phone Experience. 
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 # Optional
    }

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

​
Add the auth0_branding_phone_notification_template resource (optional)

If you use enrollment_message or verification_message on the legacy Guardian phone block to customize one-time passcode (OTP) message text, you can replicate that behavior with the auth0_branding_phone_notification_template resource. 
resource "auth0_branding_phone_notification_template" "default" {
    # See the Auth0 Terraform Provider documentation for available template variables.
}

​
Clean up the Auth0 Guardian resource phone block

Remove all legacy provider-specific attributes from the auth0_guardian phone block. After cleanup, the block should contain only the enabled and message_types attributes plus a depends_on block that references the auth0_tenant.main and auth0_phone_provider.default resources. This applies UPE and phone-provider configuration before the legacy Guardian phone block. 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"]
    }
    depends_on = [auth0_tenant.main, auth0_phone_provider.default]
}

​
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 = true)
  • auth0_branding_phone_notification_template.default created (if added)
terraform plan
terraform apply

​
Troubleshooting

​
403 Forbidden errors during terraform apply

This error typically means that phone_consolidated_experience was already set to true when Terraform tried to manage legacy Guardian phone attributes. Ensure that the depends_on block references auth0_tenant.main and auth0_phone_provider.default so that Terraform applies them in the correct order.

​
409 Conflict error: Message Type is not supported by the configured phone provider

This error means the message_types value on the auth0_guardian resource is not supported by the configured provider. Ensure the provider’s delivery_methods covers the requested message_types. Use message_types: ["sms"] for text delivery, or message_types: ["voice"] for voice delivery.

​
Terraform apply error: Provider or options cannot be specified

The legacy auth0_guardian resource still has a provider attribute or options block while UPE is enabled. Remove provider and options from the configuration so the phone block contains only the enabled and message_types settings.

​
Custom phone provider not delivering messages

Verify that the Auth0 Action with the custom-phone-provider trigger exists and is deployed in Auth0 before you run terraform apply.

​
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.