Configure an SMS Provider

ThunderID sends SMS messages, such as One-Time Passwords (OTPs), through an SMS connection. An SMS connection links ThunderID to a messaging provider that delivers SMS to end users.

Three messaging providers are supported:

• Twilio: requires an Account SID, Auth Token, and Sender ID
• Vonage: requires an API Key, API Secret, and Sender ID
• Custom: connects to any SMS gateway via an HTTP webhook

Prerequisites

• A ThunderID instance running and accessible
• You can sign in to the ThunderID Console
• An active account with your chosen messaging provider

Add an SMS Provider

Twilio

1. Log in to Twilio and retrieve your Account SID, Auth Token, and the phone number or messaging service SID to use as the sender.

2. Sign in to the ThunderID Console and navigate to Connections.

3. Click the Twilio card. If the card shows Not configured, this opens a form to create the connection. If it already shows Configured, this opens the existing connection instead.

4. Enter the following fields, then click Create connection:

   Field	Description
   Account SID	Twilio Account SID, starting with AC followed by 32 hex characters.
   Auth token	Twilio auth token used to authenticate API requests.
   Sender ID	The Twilio phone number or messaging service SID used as the sender.

Vonage

1. Log in to the Vonage API Dashboard and retrieve your API Key, API Secret, and sender name or virtual number.

2. Sign in to the ThunderID Console and navigate to Connections.

3. Click the Vonage card. If the card shows Not configured, this opens a form to create the connection. If it already shows Configured, this opens the existing connection instead.

4. Enter the following fields, then click Create connection:

   Field	Description
   API key	Vonage API key from your Vonage dashboard.
   API secret	Vonage API secret used to authenticate API requests.
   Sender ID	Phone number or alphanumeric sender ID messages are sent from.

note

Vonage requires the recipient phone number in E.164 format without a leading + or 00. ThunderID strips these prefixes automatically before sending.

Custom Provider

note

The Console's SMS gateway connection type is coming soon. Until it ships, create a custom SMS gateway connection through the API.

Use the sms-gateway connection to connect ThunderID to any SMS gateway that accepts HTTP requests. Send a POST request to /connections/sms-gateway with an access token that has the system scope:

curl -X POST https://localhost:8090/connections/sms-gateway \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <access_token>" \
  -d '{
    "name": "CustomSMSSender",
    "description": "Custom HTTP webhook for SMS delivery",
    "url": "https://sms.example.com/send",
    "httpMethod": "POST",
    "contentType": "JSON",
    "httpHeaders": "X-API-Key: <key>"
  }'

SMS Gateway Fields

Field	Required	Secret	Description
url	✅	❌	Full URL of the SMS gateway endpoint.
httpMethod	❌	❌	HTTP method to use. Supported values: GET, POST.
contentType	❌	❌	Request body format. Supported values: JSON, FORM.
httpHeaders	❌	❌	Comma-separated list of additional HTTP headers in Key: Value format.

See the Connections API Reference for the full request and response shapes.

Customize the Gateway Request Body

ThunderID does not assemble a request payload for the gateway. It sends the rendered SMS template as the request body exactly as written. The template defines both the payload shape and the field names your gateway expects.

To change the request body, edit the SMS template for the scenario your flow uses, such as sms_otp.yaml for the OTP scenario. Templates load at startup, so restart the server after editing one.

For a connection with contentType set to JSON, write the template body as the JSON object your gateway accepts:

body: '{"to":"{{ctx(mobile_number)}}","body":"Your verification code is {{ctx(otpCode)}}."}'

For FORM, write one key=value pair per line:

body: |
  to={{ctx(mobile_number)}}
  message=Your verification code is {{ctx(otpCode)}}

Keep the template's contentType set to text/plain. With text/html, ThunderID escapes HTML characters in substituted values, which breaks JSON quoting.

Update an SMS Provider

1. Open the connection from the Connections page.
2. On the General tab, edit the fields under Credentials.
3. Stored secrets, such as Auth token or API secret, are write-only: the field stays locked until you click Update. Leave it unchanged to keep the stored secret.
4. Click Save changes in the bar at the bottom of the page. You can click Discard instead to abandon your edits.

note

A connection's vendor cannot be changed after creation. To switch providers, delete the existing connection and create a new one for the new vendor.

Remove an SMS Provider

1. Open the connection from the Connections page.
2. On the General tab, go to Danger zone and click Delete connection.
3. Confirm the deletion in the dialog.

If another resource still references this SMS provider, the dialog lists the resources and blocks the deletion until you remove or update them.

Next Steps

• Build a Flow: Add an SMS OTP step to a sign-in or registration flow