接口描述
向用户发送短信或邮箱 OTP 验证码,用于登录、注册或更新用户信息。
支持的应用类型
Web 应用、M2M 应用。
请求方法
POST
请求路径
/otp/send
请求 Content-Type
application/json
请求示例
短信 OTP 登录场景,发送短信验证码用于登录。
POST /otp/send HTTP/1.1Content-Type: application/jsonAuthorization: Basic VEVOQU5UX0NMSUVOVF9JRDpURU5BTlRfQ0xJRU5UX1NFQ1JFVA==Host: sample.portal.tencentciam.com{"usage" : "login","phone_number" : "13612345678","auth_source_id" : "MOCK_SMS_OTP_AUTH_SOURCE_ID"}
邮箱 OTP 登录场景,发送邮箱验证码用于登录。
POST /otp/send HTTP/1.1Content-Type: application/jsonAuthorization: Basic Q0xJRU5UXzRfSUQ6Q0xJRU5UXzRfU0VDUkVUHost: sample.portal.tencentciam.com{"usage" : "login","email" : "MOCK_USERNAME@example.com","auth_source_id" : "MOCK_EMAIL_OTP_AUTH_SOURCE_ID"}
用户注册场景,发送短信验证码用于绑定手机。
POST /otp/send HTTP/1.1Content-Type: application/jsonAuthorization: Basic Q0xJRU5UXzRfSUQ6Q0xJRU5UXzRfU0VDUkVUHost: sample.portal.tencentciam.com{"usage" : "signup","phone_number" : "13612345678"}
用户注册场景,发送邮箱验证码用于绑定邮箱。
POST /otp/send HTTP/1.1Content-Type: application/jsonAuthorization: Basic Q0xJRU5UXzRfSUQ6Q0xJRU5UXzRfU0VDUkVUHost: sample.portal.tencentciam.com{"usage" : "signup","email" : "MOCK_USERNAME@example.com"}
更新用户信息场景,发送短信验证码绑定或更新手机号。
POST /otp/send HTTP/1.1Content-Type: application/jsonAuthorization: Basic Q0xJRU5UXzRfSUQ6Q0xJRU5UXzRfU0VDUkVUHost: sample.portal.tencentciam.com{"usage" : "update_userinfo","phone_number" : "13612345678"}
重置密码场景,发送邮箱验证码。
POST /otp/send HTTP/1.1Content-Type: application/jsonAuthorization: Basic Q0xJRU5UXzRfSUQ6Q0xJRU5UXzRfU0VDUkVUHost: sample.portal.tencentciam.com{"usage" : "reset_password","email" : "MOCK_USERNAME@example.com"}
请求头
名称 | 描述 |
Authorization | HTTP Basic 认证请求头,格式为 Basic <credentials> ,其中 Basic 为固定字符串,<credentials> 的计算方式为 base64(url_encode(client_id) + ":" + url_encode(client_secret)) ,Basic 和 <credentials> 之间用一个空格隔开。 |
请求体 JSON 参数
JSON 路径 | 数据类型 | 描述 |
usage | String | OTP 验证码的使用场景。 短信和邮箱 OTP 登录场景输入 login 。用户注册场景输入 signup 。更新用户信息场景输入 update_userinfo 。重置用户密码场景输入 reset_password 。如果没有输入参数,默认代表登录场景。 |
phone_number | String | 用户的手机号,限国内三大运营商11位手机号。发送短信 OTP 验证码时传递此参数。 |
email | String | 用户的邮箱地址。发送邮箱 OTP 验证码时传递此参数。 |
auth_source_id | String | 短信 OTP 或邮箱 OTP 认证源 ID。可在控制台的通用认证源列表页面查看。短信和邮箱 OTP 登录场景传递此参数,系统将使用认证源配置的验证码长度和有效期。其他场景不传递此参数,系统默认使用6位数字验证码,有效期60秒。 |
正常响应示例
验证码发送成功。
HTTP/1.1 200 OKContent-Type: application/json{"otp_token" : "MOCK_OTP_TOKEN"}
响应参数
字段 | 数据类型 | 描述 |
otp_token | String | OTP token,后续验证 OTP 时携带使用。有效期5分钟。 |
异常响应示例
手机号格式有误。
HTTP/1.1 400 Bad RequestContent-Type: application/json;charset=UTF-8{"error" : "malformed_phone_number"}
邮箱格式有误。
HTTP/1.1 400 Bad RequestContent-Type: application/json;charset=UTF-8{"error" : "malformed_email"}
因短信额度不足无法发送短信,一般是由于免费短信额度已用尽,需要到控制台配置 短信模板。
HTTP/1.1 400 Bad RequestContent-Type: application/json;charset=UTF-8{"error" : "insufficient_sms_quota"}
因邮箱额度不足无法发送邮件,一般是由于免费邮箱额度已用尽,需要到控制台配置 邮箱模板。
HTTP/1.1 400 Bad RequestContent-Type: application/json;charset=UTF-8{"error" : "insufficient_email_quota"}
邮箱地址不存在或在黑名单中。
HTTP/1.1 400 Bad RequestContent-Type: application/json;charset=UTF-8{"error" : "invalid_email"}
验证码发送失败。
HTTP/1.1 503 Service UnavailableContent-Type: application/json;charset=UTF-8{"error" : "temporarily_unavailable","error_description" : "Failed to send OTP. Please try again later."}
注册场景,邮箱被使用。
HTTP/1.1 400 Bad RequestContent-Type: application/json;charset=UTF-8{"error": "email_is_used"}
注册场景,手机号被使用。
HTTP/1.1 400 Bad RequestContent-Type: application/json;charset=UTF-8{"error": "phone_number_is_used"}
向单个手机号发送短信频率超限。
如果使用的是自购短信服务,可自行到 短信控制台 调整短信频率限制策略。
如果使用的是免费短信额度,频率限制为:对同一手机号,每个自然日内发送短信条数不超过50条;相同内容短信对同一手机号,30秒内发送短信条数不超过1条。
HTTP/1.1 400 Bad RequestContent-Type: application/json;charset=UTF-8{"error" : "sms_rate_limit_exceeded","error_description" : "SMS rate limit exceeded for same phone number"}