Web API 身份验证
更新时间：2021-11-03 09:13
我们支持两种认证方式：API密钥认证 和 OAuth认证。
API密钥认证
请求时请添加以下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认证
使用步骤：
A) EffiLink用户访问第三方服务，第三方服务通过构造OAuth2链接，来为用户展示EffiLink的授权页。
B) 用户选择是否同意授权。
C) 若用户同意授权，则EffiLink将用户重定向到第一步指定的重定向URI，同时附上一个授权码（code）。
D) 第三方服务收到授权码（code），向EffiLink申请凭证（AccessToken）。
E) EffiLink检查授权码（code）的有效性，通过后颁发凭证（AccessToken）。
F) 第三方服务通过此凭证（AccessToken）访问EffiLink的业务 API。
使用OAuth2前：须在EffiLink平台配置OAuth应用
授权过程中使用的client_id（应用Id）、client_secret（应用密钥）、redirect_uri（重定向地址）需要在平台配置：
第一步：构造EffiLink的OAuth2授权页链接
GET /v5/auth/oauth/authorize
请求参数
| 名称 | 必填 | 描述 | 示例值 |
|---|---|---|---|
| client_id | 是 | OAuth应用Id | 1751651162214168 |
| response_type | 是 | 返回类型 | 固定值：code |
| redirect_uri | 是 | 授权后重定向的回调链接地址，请使用urlencode对链接进行处理 | https%3A%2F%2Fapp.effilink.co%2FoauthCodeCallback |
| scope | 是 | 应用授权作用域。 | 固定值：All |
请求示例
curl --request GET \
--url https://api.effilink.co/v5/auth/oauth/authorize?client_id=1751651162214168&response_type=code&redirect_uri=https%3A%2F%2Fapp.effilink.co%2FoauthCodeCallback&scope=All
请求返回
返回EffiLink授权页。
用户在授权页授权后，将重定向到传递的redirect_uri参数值，并且携带code参数。注意，code的有效期为5分钟。
第二步：通过授权码（code）获取凭证（AccessToken）
GET /v5/auth/oauth/token
请求参数
| 名称 | 必填 | 描述 | 示例值 |
|---|---|---|---|
| grant_type | 是 | 授权方式 | 固定值：authorization_code |
| client_id | 是 | OAuth应用Id | 1751651162214168 |
| client_secret | 是 | OAuth应用密钥 | 768e04e13b5f4a3ca67de0a21b3ca7d5 |
| code | 是 | 用户授权后重定向返回的code值 | ae3cae67d13b5fe0a21b3cae7d |
请求示例
curl --request GET \
--url https://api.effilink.co/v5/auth/oauth/token?grant_type=authorization_code&client_id=1751651162214168&client_secret=768e04e13b5f4a3ca67de0a21b3ca7d5&code=ae3cae67d13b5fe0a21b3cae7d
返回参数
| 名称 | 类型 | 描述 |
|---|---|---|
| code | int | 返回码 |
| message | string | 对返回码的文本描述内容 |
| accessToken | string | 获取到的凭证，最长为512字节。同一个ApiKey在凭证的有效期内仅会生成一个相同的AccessToken |
| expiresIn | int | 凭证的剩余有效时间（秒）。-1表示永久有效。有效期剩余5分钟以内时，可生成一个新的AccessToken，在此期间新老AccessToken同时有效 |
返回示例
{
"code": 200,
"message": null,
"accessToken": "5cb089d6eafd49caa68c41b9be9af6f6",
"expiresIn": -1
}
第三步：使用凭证（AccessToken）访问 API
请求时请添加以下Header来身份验证：
| Header名称 | 必填 | 描述 | 示例值 |
|---|---|---|---|
| OAuth | 是 | OAuth认证的accessToken | 5cb089d6eafd49caa68c41b9be9af6f6 |
示例
curl --request POST \
--url https://api.effilink.co/v5/transactional/mail/sends_customised \
--header 'OAuth: 5cb089d6eafd49caa68c41b9be9af6f6'
--data ...