Migrate to Unified Phone Experience with Terraform

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:

Auth0 Terraform Provider v1.49.0 or later.
If you want to configure a custom phone provider, create and deploy a custom-phone-provider Auth0 Action to handle message delivery.

Enable the phone provider resource and remove legacy configuration

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

Set the phone_consolidated_experience flag to true
Add the tenant-level phone provider
Add the auth0_branding_phone_notification_template resource (optional)
Clean up the auth0_guardian resource phone block
Plan and apply

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.

Twilio
Custom (Actions)

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"].

resource "auth0_phone_provider" "default" {
    name = "custom"

    configuration {
        delivery_methods = ["text"]
    }
}

For a custom phone provider, Auth0 expects the custom-phone-provider Action to be deployed before you run terraform apply. The Action handles delivery.

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.

Brand Customization

Code Customization

Third-Party Customization

Migrate to Unified Phone Experience with Terraform

Prerequisites

Enable the phone provider resource and remove legacy configuration

Set the consolidated experience flag

Add the tenant-level phone provider

Add the auth0_branding_phone_notification_template resource (optional)

Clean up the Auth0 Guardian resource phone block

Plan and apply

Troubleshooting

403 Forbidden errors during terraform apply

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

Terraform apply error: Provider or options cannot be specified

Custom phone provider not delivering messages

OTP messages not arriving after migration

​Prerequisites

​Enable the phone provider resource and remove legacy configuration

​Set the consolidated experience flag

​Add the tenant-level phone provider

​Add the auth0_branding_phone_notification_template resource (optional)

​Clean up the Auth0 Guardian resource phone block

​Plan and apply

​Troubleshooting

​403 Forbidden errors during terraform apply

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

​Terraform apply error: Provider or options cannot be specified

​Custom phone provider not delivering messages

​OTP messages not arriving after migration

Prerequisites

Enable the phone provider resource and remove legacy configuration

Set the consolidated experience flag

Add the tenant-level phone provider

Add the auth0_branding_phone_notification_template resource (optional)

Clean up the Auth0 Guardian resource phone block

Plan and apply

Troubleshooting

403 Forbidden errors during terraform apply

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

Terraform apply error: Provider or options cannot be specified

Custom phone provider not delivering messages

OTP messages not arriving after migration