Server API 鉴权

Server API 供客户业务后端调用，用于用户同步、Session 签发、业务群和消息扩展。客户端 SDK 使用用户 IM Session，不接触这些服务端签名凭据。

请求 Header

Header	内容
X-Client-Id	部署方配置的调用方标识
X-Timestamp	当前 Unix 毫秒时间戳
X-Nonce	每次 HTTP 请求新生成的随机值
X-Signature	HMAC-SHA256 小写十六进制签名
X-Trace-Id	便于跨服务排查的追踪标识
X-Idempotency-Key	写操作的逻辑动作标识

服务端同时校验签名与调用方路径权限，请按业务需要配置允许访问的 API。

签名原文

大写 HTTP 方法 + 请求路径 + 毫秒时间戳 + nonce + SHA256(原始 body)

五部分直接拼接，不加入换行或其他分隔符。存在查询字符串时，路径包含实际发送的原始查询部分，不能在签名后重排参数或改变编码。请求体摘要使用实际发送的 UTF-8 字节。

下面是 Node.js 的纯签名函数，不会发起网络请求。secret 由客户后端的密钥管理方式注入。

import { createHash, createHmac } from 'node:crypto';

export function signServerRequest({
  method, requestPath, timestamp, nonce, rawBody, secret,
}) {
  const bodyHash = createHash('sha256').update(rawBody).digest('hex');
  const canonical = method.toUpperCase()
    + requestPath + timestamp + nonce + bodyHash;
  return createHmac('sha256', secret)
    .update(canonical, 'utf8')
    .digest('hex');
}

rawBody 推荐传 Buffer：先把 JSON 序列化一次，将同一个字节数组用于签名和发送。不要签名紧凑 JSON 后又发送缩进 JSON。

幂等与重试

“同一次业务动作”与“同一次网络请求”需要区分。业务动作重试时复用 X-Idempotency-Key 和原始请求内容，但使用新的时间戳、nonce 和签名，避免触发防重放。

每次新 Session 续期、新消息或新群变更使用新的幂等键；同键不同内容不能作为一个新动作。网络超时或服务暂时不可用可以按同一动作退避重试；签名、权限和参数错误应先修正。

常见验签问题

表现	优先核对
时间戳过期	是否用了秒、机器时钟是否偏差
签名不一致	body 字节、路径编码、查询顺序、分隔符
nonce 已使用	重试是否沿用了整套 Header
签名正确仍拒绝	调用方路径权限与业务权限

Webhook 使用另一种带换行的签名原文，不能直接套用本页函数，见 Webhook 接入。下一步：同步用户与业务群。