鉴权认证

快速阅读

OpenAPI 调用使用「接口密钥 + 请求签名 + 权限校验」。一次请求只走一种鉴权方式，不要混用参数。

管理端「接口密钥」生成访问密钥 ID 和 Secret / Token。只有启用状态、且已分配对应接口权限的密钥可以调用。
MD5 签名：validateType=1 用部门编号，validateType=2 用呼叫中心编号。sign 是 32 位小写 MD5。timestamp 为秒级 Unix 时间戳，有效期 30 分钟。
AK/SK 签名：请求带 AccessKeyId 时走这一路。还要带 Timestamp（UTC）、Expires（1～86400 秒）和 Signature（HMAC-SHA1）。
全链路加密：请求头带 Tinet-Sign、Tinet-Timestamp、Tinet-Enterprise-Id 等。时间窗 5 分钟。验签通过后不再走 MD5 或 AK/SK，仍校验 IP 白名单和频控。
region 只选择接入区域，不改变各方式自己的签名公式。企业应使用哪个 region，见 CTICloud 地域说明。

阅读地图

密钥在哪里建、怎么授权：读「三」「四」。
请求里带哪些参数、签名怎么算：读「五」。
平台按什么顺序验：读「六」。
上线前验什么、失败先查什么：读「七」「八」。

一、文档说明

本文说明外部业务系统调用呼叫中心 OpenAPI 时的鉴权。适用对象：外部系统开发、为外部系统开通接口权限的管理员、配置请求凭证的实施人员。

本文主要说明接口密钥、三种鉴权方式（MD5、AK/SK、全链路加密）和权限校验。管理端登录、座席登录、菜单权限和座席上线认证见对应专题。

二、鉴权链路

调用方先在管理端生成接口密钥。请求到达后，平台先识别鉴权方式：全链路加密已通过则跳过 MD5/AK/SK；否则带 AccessKeyId 走 AK/SK，其余走 MD5。再校验密钥状态、签名、时间窗、IP 白名单、频控和接口权限，通过后才执行业务接口。

生成密钥 -> 分配权限 -> 调用方按一种方式签名
  → 全链路加密已通过：跳过 MD5 / AK/SK，继续 IP 与频控
  → 带 AccessKeyId：AK/SK
  → 其余：MD5
  → 权限校验 -> 返回接口结果

三、凭证

3.1 接口密钥

管理端通过「接口密钥」页面维护 OpenAPI 调用凭证。

配置项	作用	要求
访问密钥 ID	标识调用方身份	交付给对接方，用于接口请求
密钥 Secret / Token	参与签名计算	只在安全渠道交付，不写入公开文档
状态	控制密钥是否可用	只有启用状态可用于调用
分配权限	控制可访问接口范围	按最小权限分配
备注	记录用途和归属	建议填写系统名、项目名、负责人

3.2 三种鉴权方式

一次请求只使用一种方式。参数不要混在同一请求里。

方式	怎么识别	时间窗	签名
MD5	不带 `AccessKeyId`，使用 `validateType`、`sign`	`timestamp` 30 分钟	32 位小写 MD5
AK/SK	查询参数带 `AccessKeyId`	`Timestamp` 为 UTC；`Expires` 为 1～86400 秒	HMAC-SHA1，参数名 `Signature`
全链路加密	请求头带 `Tinet-Sign` 等	`Tinet-Timestamp` 5 分钟	与密文 Body 配套；验签通过后不再走 MD5 或 AK/SK

全链路加密常见请求头：Tinet-Sign、Tinet-Timestamp、Tinet-Enterprise-Id、Tinet-Token、Tinet-Key-Id、Tinet-Encrypt-Version。Body 为密文。联调清单按所选方式拆开验收，不要用 MD5 的时间窗去验全链路加密。

3.3 MD5 签名规则

不同 region 使用不同接入地址。签名规则相同：使用正确的 region id、企业或部门身份参数、时间戳和签名。

region：接入区域，不同区域使用不同 region id。
validateType=1：使用部门编号鉴权，sign=MD5(departmentId + timestamp + 部门token)。
validateType=2：使用呼叫中心编号鉴权，sign=MD5(enterpriseId + timestamp + 部门token)。
timestamp：秒级 Unix 时间戳，有效期 30 分钟。
sign：32 位小写 MD5。

四、配置步骤

4.1 新建密钥

管理员进入「接口密钥」页面。
查看密钥对占用情况，确认未超过上限。
点击「生成密钥对」。
记录访问密钥 ID，并通过安全方式交付 Secret / Token。
填写备注，标明系统、项目和负责人。

4.2 分配权限

在密钥列表找到对应访问密钥 ID。
点击「分配权限」。
只勾选本次对接需要的接口权限。
保存后由对接方发起接口请求验证。

权限分配：

查询类系统只分配查询接口。
录音、话单、外呼任务等敏感能力单独确认权限。
每个外部系统使用独立密钥。
项目结束或系统下线后禁用或回收密钥。

4.3 禁用与回收

密钥疑似泄露、系统下线、归属不清或临时停止访问时，先执行「禁用」。确认不再使用后，再移入回收站。

禁用后，该密钥不再通过 OpenAPI 鉴权。

五、请求参数

按所选鉴权方式带参。下面先列 MD5。AK/SK 必填 AccessKeyId、Timestamp、Expires、Signature。全链路加密把身份和签名放在 Tinet-* 请求头，不要再套 MD5 查询参数。

参数	是否必填	说明
`region`	是	接入区域标识，不同区域使用不同 region id
`validateType`	是	`1` 表示部门编号鉴权，`2` 表示呼叫中心编号鉴权
`departmentId`	条件必填	`validateType=1` 时必填
`enterpriseId`	条件必填	`validateType=2` 时必填
`timestamp`	是	秒级 Unix 时间戳，有效期 30 分钟
`sign`	是	按规则生成的 32 位小写 MD5

示例：

region=1
validateType=1
departmentId=BM0000001
timestamp=1491371625
sign=MD5(BM0000001 + 1491371625 + 部门token)

region 只用于选择接入区域，不改变鉴权主体和签名规则。确认当前企业或部门应使用的 region id，并与请求地址、企业归属一致。更换 region 后重新发起联调验收。

六、平台校验顺序

识别调用方身份
  ↓
检查密钥是否存在且启用
  ↓
校验 timestamp 是否在有效期内
  ↓
按平台规则重新计算签名
  ↓
比较请求签名与服务端签名
  ↓
检查该密钥是否具备接口权限
  ↓
执行业务接口并返回结果

任一环节失败，返回鉴权失败或无权限结果，不继续执行业务逻辑。

七、联调验收

上线前至少完成以下验证：

使用正确密钥调用一个已授权接口，预期成功。
使用错误 Secret / Token 调用，预期鉴权失败。
使用过期 timestamp 调用（MD5），或过期 Timestamp/Expires（AK/SK），或过期 Tinet-Timestamp（全链路加密），预期鉴权失败。
AK/SK 联调确认请求带 AccessKeyId，且未同时按 MD5 公式签名。
全链路加密联调确认 Tinet-* 头齐全、时间窗按 5 分钟验收。
使用未分配权限的接口调用，预期无权限。
禁用密钥后再次调用，预期鉴权失败。
更换新密钥后，旧密钥不可用，新密钥可用。

八、常见失败处理

现象	优先检查项
签名错误	Secret / Token 是否正确，签名公式、参数顺序、大小写是否一致
时间戳无效	服务器时间是否准确；MD5 的 `timestamp` 是否为秒级且未超 30 分钟；AK/SK 的 `Timestamp` 是否为 UTC、`Expires` 是否在 1～86400；全链路加密是否超 5 分钟
无权限	是否已给该密钥分配对应接口权限
密钥不可用	密钥是否被禁用、回收或超过数量治理策略
region 不匹配	region id、请求地址、企业编号或部门编号是否属于同一接入区域
环境不匹配	endpoint、区域、企业编号、部门编号是否与当前环境一致

九、安全要求

Secret / Token 只允许通过安全渠道交付。
不在截图、日志、工单、公开文档中明文展示密钥。
每个系统使用独立密钥，便于权限收敛和风险切断。
定期检查长期未使用、备注为空、归属不清的密钥。
发现泄露风险时，先禁用旧密钥，再生成新密钥替换。