Web API 身份验证

更新时间：2021-11-03 09:13

我们支持两种认证方式：签名认证和 OAuth认证。

签名认证

请求时请添加以下Header来身份验证，其中的ApiKey、ApiSecret需要在平台获得：

Header名称	必填	描述	示例值
ApiKey	是	API访问ID	3BTWNKN0ZDQIZBQ33XCO
Timestamp	是	请求的时间戳，为日期格式。时效期限：5分钟，过期时间戳将无法通过验证。采用UTC标准时间，遵循ISO8601日期时间格式。具体格式：YYYY-MM-DDThh:mm:ssZ	示例：北京时间（UTC+8）2023年1月10日20:00:00 → UTC标准时间表示为 2023-01-10T12:00:00Z
Authorization	是	签名字符串生成规则：使用双重SHA1哈希算法，先对API密钥(ApiSecret)进行SHA1哈希并转为大写，再拼接请求头中的时间戳(Timestamp)，最后对拼接结果进行SHA1哈希运算。说明：ApiSecret是与ApiKey配对的密钥，Timestamp取自请求头中的Timestamp字段。	示例：一、原始API密钥：VzNnMBUbDLloZkKMHqEeqg2byrNpVyrqf-XI1sAk 二、对密钥进行SHA1哈希并转为大写：12DF57B52BF86ABA6E25F15AE1936618118787D6 三、拼接时间戳"2023-01-10T12:00:00Z"后进行二次SHA1哈希四、最终签名值：788A8BD4915B1DBFF175A54B14A8771BBAF99FC9
SignatureVersion	否	签名算法版本。默认值：1.0	1.0

示例

curl --request POST \
  --url https://api.effilink.co/v5/transactional/mail/sends_customised \
  --header 'ApiKey: '3BTWNKN0ZDQIZBQ33XCO'
  --header 'Timestamp: '2025-05-21T08:30:45Z'
  --header 'Authorization: '788A8BD4915B1DBFF175A54B14A8771BBAF99FC9'
  --header 'SignatureVersion: '1.0'
  --data ...

身份验证相关的状态码：

状态码	说明
200	OK，请求处理成功。
401	Unauthorized，权限认证未通过。
403	Forbidden，请求拒绝。如请求参数问题等。
500	Internal Server Error，内部服务异常。

OAuth认证

使用步骤：客户端向授权 API 请求 token，授权 API 验证身份并返回访问令牌（access token），客户端携带访问令牌（access token）访问业务 API 方法。

第一步：请求 token

GET /v5/auth/oauth/authorize?grantType=client_credentials

请求头

名称	必填	描述	示例值
Authorization	是	OAuth的认证数据。格式：base64(ApiKey:ApiSecret)	如：ApiKey为E45GAUDURWH68BU8J59I，ApiSecret为9B20CC02686312C01002DBF6DD749EFBDD963B78，生成值base64(E45GAUDURWH68BU8J59I:9B20CC02686312C01002DBF6DD749EFBDD963B78)为RTQ1R0FVRFVSV0g2OEJVOEo1OUk6OUIyMENDMDI2ODYzMTJDMDEwMDJEQkY2REQ3NDlFRkJERDk2M0I3OA==

参数

名称	类型	必填	描述	示例值
grantType	string	是	OAuth的授权类型	取值范围：client_credentials

请求示例

curl --request GET \
  --url https://api.effilink.co/v5/auth/oauth/authorize?grantType=client_credentials \
  --header 'Authorization: RTQ1R0FVRFVSV0g2OEJVOEo1OUk6OUIyMENDMDI2ODYzMTJDMDEwMDJEQkY2REQ3NDlFRkJERDk2M0I3OA=='

返回参数

名称	类型	描述
code	int	返回码
message	string	对返回码的文本描述内容
accessToken	string	获取到的凭证，最长为512字节。同一个ApiKey在凭证的有效期内仅会生成一个相同的AccessToken
expiresIn	int	凭证的剩余有效时间（秒）。新生成的AccessToken的有效期为2小时。有效期剩余5分钟以内时，可生成一个新的AccessToken，在此期间新老AccessToken同时有效

返回示例

{
    "code": 200,
    "message": null,
    "requestId": "896e99c710bd4ead88e4f9c3352cc9ae",
    "accessToken": "5cb089d6eafd49caa68c41b9be9af6f6",
    "expiresIn": 7200
}

第二步：携带 access token 访问 API

请求时请添加以下Header来身份验证)：

Header名称	必填	描述	示例值
OAuth	是	OAuth认证的accessToken	5cb089d6eafd49caa68c41b9be9af6f6

示例

curl --request POST \
  --url https://api.effilink.co/v5/transactional/mail/sends_customised \
  --header 'OAuth: 5cb089d6eafd49caa68c41b9be9af6f6'
  --data ...