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 when using a phone number as a user identifier. This feature uses Actions to route the SMS messages to a phone provider of your choice when verifying phone numbers and resetting passwords.
Configuring a custom phone provider uses an Action trigger called custom-phone-provider that is not available in the Auth0 Actions editor. The custom-phone-provider trigger is distinct from the existing send-phone-message trigger, which should not be used for configuring a custom phone provider. Only use the custom-phone-provider trigger to configure a custom phone provider.
Configuring a custom phone provider using Actions enables you to write logic to satisfy complex use cases, including:
Using different phone providers based on application context, which may include different geographic regions where phone provider message prices can vary significantly.
Using 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.
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:
Text: The verification code will be delivered to your users via SMS.
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:
Consult with your provider's documentation to understand how to deliver messages to their API.
Add any required secrets to authenticate with the API.
(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.
(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.idtocustom-phone-provider.Consult with your provider's documentation to understand how to deliver messages to their API.
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 tocustom-phone-provider.Update the Action as needed.
Deploy the Action.