Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs-staging.auth0-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 (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.