Configure a Custom Phone Provider

Custom phone provider is currently in Early Access. To learn more about Auth0 release stages, read Product Release Stages.

You can configure a custom phone provider for SMS messages using a phone number as a user identifier. A custom phone provider uses Actions to route the SMS messages to a phone provider of your choice when verifying phone numbers and resetting passwords.

You may want to configure a custom phone provider for the following use cases:

Use different phone providers based on application context, which may include different geographic regions where phone provider message prices can vary significantly.
Use different phone providers based on organization context, where some B2B customers may require specific providers.

You can configure a custom phone provider with the Auth0 Dashboard or Management API.

Configure a custom phone provider with the Auth0 Dashboard or Management API

To configure a custom phone provider, you must use the custom-phone-provider Action trigger that is not available in the Auth0 Actions editor. The custom-phone-provider trigger is different from the send-phone-message trigger, which should not be used for configuring a custom phone provider. To learn more, read the following:

Add a custom phone provider with the Auth0 Dashboard

To configure a new custom phone provider in the Auth0 Dashboard:

Navigate to Branding > Phone Provider. This takes you to the Phone Message Provider page. By default, the Twilio phone provider is selected.
Select the Custom phone provider option in the Phone Provider section.
Select the Delivery Method:
1. Text: The verification code will be delivered to your users via SMS.
2. Voice: The verification code will be delivered to your users via Voice Message.
Under Provider Configuration, write your actions code to configure a custom phone provider:
1. Consult with your provider's documentation to understand how to deliver messages to their API.
2. Add any required secrets to authenticate with the API.
3. (Optional) You can edit the Action using the full Actions editor interface by clicking the Edit in Expanded Editor button. After editing your action in the Actions editor, Save and Deploy the Action from that interface. Click the Back to Phone Provider link at the top of the Actions editor page to return to the Phone Message Provider page. You will need to select the Custom phone provider option again in the Phone Provider section.
Click the Save button at the bottom of the page.

When you click Save, the Action automatically saves and deploys. To test the custom phone provider configuration before using it in a production environment, click Send Test Message.

You cannot click Send Test Message to test your custom phone provider until after you save your custom phone provider configuration.

Edit a custom phone provider with the Auth0 Dashboard

To edit an existing custom phone provider in the Auth0 Dashboard:

Navigate to Branding > Phone Provider. This takes you to the Phone Message Provider page.
Modify the Action code on the Phone Message Provider page as needed.
1. (Optional) You can edit the Action using the full Actions editor interface by clicking the Edit in Expanded Editor button. After editing your Action in the Actions editor, Save and Deploy the Action from that interface. Then click the Back to Phone Provider link at the top of the Actions editor page.
Click the Save button at the bottom of the page.

When you click Save, the Action automatically saves and deploys. To test the custom phone provider configuration before using it in a production environment, click Send Test Message.

Add a custom phone provider with the Management API

You can also configure a custom phone provider using the Management API. This is a multi-step process:

Create an Action and set the supported_triggers.id to custom-phone-provider.
1. Consult with your provider's documentation to understand how to deliver messages to their API.
2. Add any required secrets to authenticate with the API.
Deploy the action.
Set the phone provider to custom.

The Action you create with the custom-phone-provider trigger will not appear in the Actions library.

If no Action is deployed and you try to configure a custom provider, Auth0 will return an error with "errorCode":"custom_email_provider_deployed_action_not_found".

Edit a custom phone provider with the Management API

You can also edit a custom phone provider using the Management API.

(Optional) If you don’t know the specific Action ID, you can get the list of actions via the Management API. The response will include an Actions object. The Action used for the custom phone provider can be identified by the supported_triggers.id, which should be set to custom-phone-provider.
Update the Action as needed.
Deploy the Action.

An example of a custom phone provider you can configure is Twilio Verify. To learn more, read Configure custom phone provider with Twilio Verify.

Customize