Send One-time Codes via Your Own SMS Gateway
By default, the SMS connection uses Twilio to send the one-time code. If you already have your own infrastructure to send text messages, you cannot or might not want to use Twilio.
Instead, you'll want your own infrastructure to handle the delivery of one-time codes.
Configure your SMS Gateway
You will need to configure your own SMS Gateway through the Management API.
- Get your connections (strategy:
sms) from the GET connections endpoint.
This will return your SMS connection with your Twilio settings:
- Modify the options of the connection:
provider: Set this to
gateway_url: Set this to the URL of your SMS Gateway. Note that Auth0 must be able to reach it for this to work.
- Send the updated configuration to the Management API using the PATCH connections endpoint.
After updating the connection for any user that signs up or authenticates using the Passwordless SMS connection, the following payload will be sent to your SMS gateway:
If you set the
forward_req_info property to true, the gateway will also receive information from the HTTP request that initiated the Passwordless process. This includes the IP address of the client calling
/passwordless/start and its User Agent.
Auth0 will only consider the HTTP code returned from the SMS Gateway; it ignores the rest of the response (e.g., response body and response type).
If the SMS Gateway returns an HTTP code other than 200, the
/passwordless/start endpoint will return an HTTP 400 code and a response the looks like the following:
If the SMS Gateway returns HTTP 401, the
error_description will be Authentication failed while calling the SMS gateway: 401.
Note that the
error_description field is not part of the endpoint contract and is subject to change.
Configure an authenticated SMS Gateway
The previous settings assume your SMS Gateway accepts non-authenticated requests. The
sms_gateway provider also allows you to configure token-based authentication (using
With this configuration, when the payload is sent to the SMS Gateway, a JWT will be added to the
Authorization header which contains a token with the
audience configured in the connection and signed with the
Additionally, if your secret is base64-url-encoded, you can set