Configure a Custom Phone Provider with Terraform

Learn how to configure a custom phone provider using Terraform Auth0 Provider

You can configure a custom phone provider with the Terraform Auth0 provider. The Terraform Auth0 provider is used to interact with the Auth0 Management API in order to configure an Auth0 Tenant. To learn more, review Terraform’s Auth0 Provider documentation.

• If you are using Terraform to configure a custom phone provider, delete your existing Auth0 tenant custom phone provider.
• Auth0 has a maximum limit of one Action for Actions associated with the following triggers: custom-phone-provider and custom-email-provider.

The following steps outline how to a custom phone provider using Terraform:

1. Create an auth0_action:

resource "auth0_action" "custom_phone_provider" {
  name    = "Custom Phone Provider"
  runtime = "node22"
  deploy  = true
  code    = <<-EOT
    /**
    * Handler to be executed while sending a phone notification
    * @param {Event} event - Details about the user and the context in which they are logging in.
    * @param {CustomPhoneProviderAPI} api - Methods and utilities to help change the behavior of sending a phone notification.
    */
    exports.onExecuteCustomPhoneProvider = async (event, api) => {
      // Code goes here
      return;
    };
  EOT
  supported_triggers {
    id      = "custom-phone-provider"
    version = "v1"
  }
}

In order to bind a Terraform auth0_action to an auth0_trigger_action, set the auth0_action to deploy = true. To learn more, read Terraform’s auth0_action documentation.

2. Bind the auth0_action to the custom-phone-provider auth0_trigger_action:

resource "auth0_trigger_action" "custom_phone_provider" {
  trigger = "custom-phone-provider"
  actions {
    id           = auth0_action.custom_phone_provider.id
    display_name = auth0_action.custom_phone_provider.name
  }
  depends_on = [
    auth0_action.custom_phone_provider
  ]

3. Configure the auth0_phone_provider resource to use the auth0_action:

resource "auth0_phone_provider" "custom_phone_provider" {
  depends_on = [auth0_trigger_actions.custom_phone_provider] # Ensure the action is created first with `custom-phone-provider` as the supported_triggers
  name       = "custom"                         # Indicates a custom implementation
  disabled   = false                            # Disable the default phone provider
  configuration {
    delivery_methods = ["text", "voice"]
  }
  credentials {}

To learn more, read Terraform’s auth0_phone_provider documentation.

​

Troubleshoot

Scenario: Custom phone provider configured using Terraform is not taking effect, and the Auth0 Dashboard displays a different Action.

You may have multiple custom provider Actions with deploy: true. Auth0 has a maximum limit of one Action for Actions associated with the following triggers: custom-phone-provider and custom-email-provider.

• If you encounter this scenario, it’s recommended that you list your Actions to identify any duplicates to delete.
• If you encounter this scenario after managing your custom providers through multiple methods (Terraform, Auth0 Dashboard, Management API, and/or Auth0 SDKs) it is advisable to reset the custom provider configuration. We recommend you refrain from using multiple methods to manage your custom provider.

To reset the custom phone provider, navigate to Auth0 Dashboard > Branding and select Phone Provider. Then, select the Reset button to restore your custom provider to its default