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.

  1. Get your connections (strategy: sms) from the GET connections endpoint.

This will return your SMS connection with your Twilio settings:

  1. Modify the options of the connection:
  • provider: Set this to sms_gateway
  • gateway_url: Set this to the URL of your SMS Gateway. Note that Auth0 must be able to reach it for this to work.
  1. 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.

Error handling

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 gateway_authentication):

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 subject and audience configured in the connection and signed with the secret.

Additionally, if your secret is base64-url-encoded, you can set options.secret_base64_encoded to true.