Custom SMS Provider Configuration Guide
Overview
CloudBase Authentication supports login via phone number SMS verification codes. To use SMS verification code login, you need to integrate an SMS service provider to send verification code messages.
You can integrate the Tencent Cloud SMS provider (TENCENT_CN for Mainland China, TENCENT_INTL for International/Hong Kong, Macao, Taiwan), or integrate other SMS providers through cloud functions.
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
- Log in to the Tencent Cloud SMS Console, agree to the service agreement, and enable the SMS service.
- Go to Application Management > Application List, click Create Application, fill in the application name, and record the SdkAppId after creation.
If the SMS service and the CloudBase environment use the same Tencent Cloud account, you can integrate via CAM authorization without providing SecretId and SecretKey.
If you use a cross-account SMS service, go to API Key Management to create or view your SecretId and SecretKey.
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】. Go to the Tencent Cloud SMS Console to apply for an SMS signature. After approval, record the Signature Content for later use.
- Mainland China SMS signature: Managing Mainland China SMS Signatures
- International/Hong Kong, Macao, Taiwan SMS signature: 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}. Go to the Tencent Cloud SMS Console to apply for an SMS template. After approval, record the Template ID (TemplateId) for later use.
SMS template example:
Your verification code is: {1}, valid for {2} minutes. Do not share it with others.
For template application and review standards, refer to: 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 (required for cross-account scenarios) | API Key Management |
SecretKey | API Key (required for cross-account scenarios) | 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 |
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. template: use a custom SMS provider template (Tencent Cloud SMS uses this value) |
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 (required for cross-account scenarios; CAM authorization can be used for the same account) |
SecretKey | String | No | Tencent Cloud API key (required for cross-account scenarios; CAM authorization can be used for the same account) |
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"
}
}
}
Output Parameters
| Parameter | Type | Description |
|---|---|---|
RequestId | String | Unique request ID, used for troubleshooting |
Response Example
{
"Response": {
"RequestId": "70b8908d-5c99-4a20-be23-f84aff0bfd37"
}
}
Notes
-
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.
-
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.
-
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.
-
Store SecretKey securely: Do not hardcode the SecretKey in front-end code. It is recommended to call the API through a backend service.
-
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.