> ## Documentation Index
> Fetch the complete documentation index at: https://auth0.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Migrate to Unified Phone Experience with Terraform

> Learn how to migrate from the legacy Guardian phone configuration to the Unified Phone Experience using the Auth0 Terraform Provider.

Migrate your tenant from the legacy [Auth0 Guardian](/docs/secure/multi-factor-authentication/auth0-guardian) phone configuration to the [Unified Phone Experience (UPE)](/docs/customize/phone-messages/unified-phone/configure-unified-phone) using the Auth0 [Terraform Provider](https://registry.terraform.io/providers/auth0/auth0/latest/docs).

After migration, all [multi-factor authentication (MFA) phone notifications](/docs/customize/phone-messages/unified-phone/use-auth0s-unified-phone-experience-for-multi-factor-authentication) route through a single tenant-level phone provider.

## Prerequisites

Before you begin migration, you need:

* [Auth0 Terraform Provider v1.49.0](https://registry.terraform.io/providers/auth0/auth0/latest) or later.
* If you want to configure a custom phone provider, create and deploy a [`custom-phone-provider`](/docs/customize/phone-messages/configure-phone-messaging-providers/configure-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](#set-the-phone-consolidated-experience-flag-to-true)
* [Add the tenant-level phone provider](#add-the-tenant-level-phone-provider)
* [Add the auth0\_branding\_phone\_notification\_template resource (optional)](#add-the-auth0-branding-phone-notification-template-resource-optional)
* [Clean up the auth0\_guardian resource phone block](#clean-up-the-auth0-guardian-resource-phone-block)
* [Plan and apply](#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`](https://registry.terraform.io/providers/auth0/auth0/latest/docs/resources/tenant) resource and set the `phone_consolidated_experience` flag to `true`.

```hcl wrap lines theme={null}
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`](https://registry.terraform.io/providers/auth0/auth0/latest/docs/resources/phone_provider) resource to handle delivery for all phone-based flows under the Unified Phone Experience.

<Tabs>
  <Tab title="Twilio">
    ```hcl wrap lines theme={null}
    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"]`.
  </Tab>

  <Tab title="Custom (Actions)">
    ```hcl wrap lines theme={null}
    resource "auth0_phone_provider" "default" {
        name = "custom"

        configuration {
            delivery_methods = ["text"]
        }
    }
    ```

    For a [custom phone provider](https://registry.terraform.io/providers/auth0/auth0/latest/docs/resources/phone_provider), Auth0 expects the [`custom-phone-provider`](/docs/customize/phone-messages/configure-phone-messaging-providers/configure-a-custom-phone-provider) Action to be deployed before you run `terraform apply`. The Action handles delivery.
  </Tab>
</Tabs>

### 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`](https://registry.terraform.io/providers/auth0/auth0/latest/docs/resources/branding_phone_notification_template) resource.

```hcl wrap lines theme={null}
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`](https://registry.terraform.io/providers/auth0/auth0/latest/docs/resources/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:**

```hcl wrap lines theme={null}
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:**

```hcl wrap lines theme={null}
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)

```bash wrap lines theme={null}
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`](#clean-up-the-auth0-guardian-resource-phone-block) 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`](#clean-up-the-auth0-guardian-resource-phone-block) 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](#clean-up-the-auth0-guardian-resource-phone-block) 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](/docs/customize/phone-messages/configure-phone-messaging-providers/configure-a-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.