Custom SMS Provider Configuration Guide

Overview

CloudBase Authentication supports login via phone number SMS verification codes. By default, the system uses CloudBase's built-in SMS quota to send verification codes. If you want to use your own SMS provider, you can configure a custom SMS channel via the API.

Currently supported providers: Tencent Cloud SMS (TENCENT_CN for Mainland China, TENCENT_INTL for International/Hong Kong, Macao, Taiwan). More providers will be supported in the future, and this guide will be updated accordingly.

Once configured, the verification code SMS triggered during signup/login will be sent through your configured SMS provider, giving you full control over the signature, template, and daily sending limit.

Prerequisites

Before calling the configuration API, you need to complete the following preparations in Tencent Cloud:

Step 1: Enable Tencent Cloud SMS Service

1. Log in to the Tencent Cloud SMS Console, agree to the service agreement, and enable the SMS service.
2. Go to Application Management > Application List, click Create Application, fill in the application name, and record the SdkAppId after creation.
3. Go to API Key Management to create or view your SecretId and SecretKey.

warning

SecretKey is a sensitive credential. Keep it secure and avoid leaking it.

Step 2: Apply for an SMS Signature

The SMS signature appears at the beginning of the SMS sent to users, for example 【Tencent Cloud】.

Mainland China SMS Signature

1. Go to Mainland China SMS > Signature Management in the left navigation of the console, and click Create Signature.
2. Fill in the details according to your actual situation:
   • Signature Purpose: Self-use (products under this account) or third-party use (third-party products, requires uploading an authorization letter)
   • Signature Type: Company, App, Trademark, Government/Public Institution, etc.
   • Signature Content: Fill in the actual displayed content, without 【】, e.g. CloudBase
3. Upload the corresponding proof documents (e.g. business license scan) and submit for review.
4. After approval, record the Signature Content for later use.

tip

Official documentation: Managing Mainland China SMS Signatures. Review hours: Weekdays 9:00–21:00, weekends 9:00–18:00, estimated around 2 hours.

International/Hong Kong, Macao, Taiwan SMS Signature (Optional)

1. Go to International/Hong Kong, Macao, Taiwan SMS > Signature Management in the left navigation of the console, and click Create Signature.
2. Fill in the signature purpose, type, and content (international signature content is 2–15 characters, without brackets).
3. Proof documents are optional (providing them can improve the approval rate). Submit for review.
4. After approval, record the Signature Content for later use.

tip

Official documentation: Managing International/Hong Kong, Macao, Taiwan SMS Signatures

Step 3: Apply for an SMS Template

The SMS template defines the body content of the verification code SMS. Variable parts are represented by placeholders {1}, {2}.

Mainland China SMS Template (Example)

Your verification code is: {1}, valid for {2} minutes. Do not share it with others.

International SMS Template (Example)

Your verification code is {1}, valid for {2} minutes. Do not share it with others.

Application Steps:

1. Go to Mainland China SMS or International/Hong Kong, Macao, Taiwan SMS > Body Template Management, and click Create Body Template.
2. Fill in the template name and template content, and select Verification Code as the SMS type.
3. Submit for review. After approval, record the Template ID (TemplateId) for later use.

tip

Official documentation: SMS Body Template Review Standards

After Completing the Preparations, You Should Have Obtained the Following Information

Parameter	Description	How to Obtain
SdkAppId	SMS Application ID	SMS Console > Application Management
SecretId	API Key ID	API Key Management
SecretKey	API Key	API Key Management
SignName	SMS Signature Content	SMS Console > Signature Management (after approval)
TemplateId	SMS Template ID	SMS Console > Body Template Management (after approval)

API Reference

Interface Information

Item	Description
Interface Name	ModifyLoginConfig (Modify Login Policy)
Request Domain	tcb.tencentcloudapi.com
API Version	2018-06-08
HTTP Method	POST
Rate Limit	20 requests/sec

tip

API documentation: ModifyLoginConfig - Modify Login Policy

Input Parameters

Top-Level Parameters

Parameter	Type	Required	Description
EnvId	String	Yes	CloudBase environment ID
PhoneNumberLogin	Boolean	Yes	Phone number SMS login switch
EmailLogin	Boolean	Yes	Email login switch
UserNameLogin	Boolean	Yes	Username/password login switch
AnonymousLogin	Boolean	Yes	Anonymous login switch
SmsVerificationConfig	Object	No	SMS verification code sending channel configuration, see details below

SmsVerificationConfig (SMS Channel Configuration)

Parameter	Type	Required	Description
Type	String	No	SMS sending channel type. default: use CloudBase built-in SMS; apis: connect to a custom API data source; template: use a custom SMS provider template (Tencent Cloud SMS uses this value)
Name	String	Required when Type is apis	Custom APIs data source identifier
Method	String	Required when Type is apis	Custom APIs method name
SmsDayLimit	Integer	No	Daily sending limit per phone number, default 30, -1 means no limit
TemplateProvider	Object	Required when Type is template	Provider SMS template configuration, see SMSProviderTemplateConfig below

SMSProviderTemplateConfig (Provider Template Configuration)

Parameter	Type	Required	Description
Vendor	String	Yes	SMS provider. TENCENT_CN: Tencent Cloud SMS (Mainland China); TENCENT_INTL: Tencent Cloud SMS (International/Hong Kong, Macao, Taiwan)
TemplateId	String	Yes	SMS template ID (approved template)
SdkAppId	String	No	Tencent Cloud SMS application ID
SignName	String	No	SMS signature content (approved signature)
SecretId	String	No	Tencent Cloud API key ID
SecretKey	String	No	Tencent Cloud API key
SenderId	String	No	Sender ID, required for some international SMS scenarios
TemplateExtendParam	Array of Object	No	Template custom extension parameters, see SMSTemplateParams below

SMSTemplateParams (Template Extension Parameters)

Parameter	Type	Description
Key	String	Parameter key (fill in when using named placeholders)
Value	String	Parameter value

Request Examples

Configure Tencent Cloud Mainland China SMS (TENCENT_CN)

{
  "EnvId": "your-env-id",
  "PhoneNumberLogin": true,
  "EmailLogin": false,
  "UserNameLogin": false,
  "AnonymousLogin": false,
  "SmsVerificationConfig": {
    "Type": "template",
    "SmsDayLimit": 100,
    "TemplateProvider": {
      "Vendor": "TENCENT_CN",
      "SdkAppId": "1400000000",
      "SecretId": "AKIDxxxxxxxx",
      "SecretKey": "xxxxxxxxxxxxxxxx",
      "SignName": "CloudBase",
      "TemplateId": "123456"
    }
  }
}

Configure Tencent Cloud International/Hong Kong, Macao, Taiwan SMS (TENCENT_INTL)

{
  "EnvId": "your-env-id",
  "PhoneNumberLogin": true,
  "EmailLogin": false,
  "UserNameLogin": false,
  "AnonymousLogin": false,
  "SmsVerificationConfig": {
    "Type": "template",
    "SmsDayLimit": 100,
    "TemplateProvider": {
      "Vendor": "TENCENT_INTL",
      "SdkAppId": "1400000000",
      "SecretId": "AKIDxxxxxxxx",
      "SecretKey": "xxxxxxxxxxxxxxxx",
      "SignName": "CloudBase",
      "TemplateId": "789012"
    }
  }
}

Restore CloudBase Built-in SMS

{
  "EnvId": "your-env-id",
  "PhoneNumberLogin": true,
  "EmailLogin": false,
  "UserNameLogin": false,
  "AnonymousLogin": false,
  "SmsVerificationConfig": {
    "Type": "default",
    "SmsDayLimit": 30
  }
}

Output Parameters

Parameter	Type	Description
RequestId	String	Unique request ID, used for troubleshooting

Response Example

{
  "Response": {
    "RequestId": "70b8908d-5c99-4a20-be23-f84aff0bfd37"
  }
}

Notes

1. Signature and template must be approved in advance: Before calling the API, ensure that both the Tencent Cloud SMS signature and template have been approved, otherwise SMS sending will fail.

2. Configure Mainland China and international scenarios separately: The SignName and TemplateId for Mainland China SMS and International/Hong Kong, Macao, Taiwan SMS are managed separately. Choose the corresponding configuration based on your user base.

3. Set SmsDayLimit reasonably: It is recommended to set a daily limit based on your business volume to prevent abnormal traffic abuse, while avoiding setting it too low to affect normal user logins.

4. Store SecretKey securely: Do not hardcode the SecretKey in front-end code. It is recommended to call the API through a backend service.

5. Configuration takes effect immediately: Once the API call succeeds, the configuration takes effect immediately. All users logging in under this CloudBase environment will use the new SMS channel.

Reference Links

• Tencent Cloud SMS Console
• Tencent Cloud SMS Quick Start
• Managing Mainland China SMS Signatures
• Managing International/Hong Kong, Macao, Taiwan SMS Signatures
• SMS Body Template Review Standards
• ModifyLoginConfig - Modify Login Policy (API Documentation)