领取预授权 Token

GET

/openapi/v3/esign/sign-grants/:grantId/token

按 grantId 领取预授权额度 Token（grantToken），用于凭预授权 Token 签名。

Token 由云签在终端用户完成预授权确认后交付 CertCloud、由 CertCloud 加密留存，两条通道二选一即可（回调加速、拉取兜底）：预授权完成时经回调 esign:grant_ready 主动推送（与 grantId 一并送达），或经本接口按 grantId 主动拉取。本接口可重复领取（幂等交付）：重复调用返回同一 Token，不会使已领取的 Token 失效。Token 在额度窗口内可反复用于签名（非一次性），直至额度耗尽 / 过期 / 撤销。

Token 是敏感凭据

grantToken 等同于「免逐次确认的签名授权」，请按敏感凭据管理：勿记录到日志、勿拼入 URL、勿存入前端本地存储，仅在服务端保存并携入凭预授权 Token 签名。

grantId 从哪来

grantId 首个入口是回调 + 主动查询双通道：预授权生效时经预授权完成回调 esign:grant_ready 主动推送（与 Token 一并送达），或经查询意愿结果按创建预授权时拿到的 willId 主动查询取得（businessStatus=SUCCEEDED 后即可，不含 Token）——回调为加速通道，未及时收到时以主动查询兜底。首次凭预授权 Token 签名的响应中也会返回同一 grantId。拿到 grantId 后，才能调本接口领取 Token、查询预授权状态或撤销——这三者均以 grantId 为入参，不能反过来用它们获得首个 grantId。

路径参数

参数	类型	必填	说明
grantId	string	是	预授权 ID

响应字段

字段	类型	说明
signGrantToken	string	预授权额度 Token（grantToken），携入凭预授权 Token 签名的 grantToken 字段
signGrantTokenExpireAt	string	Token 失效时间（毫秒时间戳字符串，长整型一律字符串，见通用说明）

请求示例

curl -X GET 'https://api.certcloud.cn/openapi/v3/esign/sign-grants/grant-xxx/token' \
  -H 'X-CC-Auth-Key: your-auth-key' \
  -H 'X-CC-Key-ID: your-key-id'

const response = await fetch('https://api.certcloud.cn/openapi/v3/esign/sign-grants/grant-xxx/token', {
  headers: {
    'X-CC-Auth-Key': 'your-auth-key',
    'X-CC-Key-ID': 'your-key-id',
  }
})

req, _ := http.NewRequest("GET", "https://api.certcloud.cn/openapi/v3/esign/sign-grants/grant-xxx/token", nil)
req.Header.Set("X-CC-Auth-Key", "your-auth-key")
req.Header.Set("X-CC-Key-ID", "your-key-id")
resp, _ := http.DefaultClient.Do(req)

import requests

resp = requests.get(
    'https://api.certcloud.cn/openapi/v3/esign/sign-grants/grant-xxx/token',
    headers={
        'X-CC-Auth-Key': 'your-auth-key',
        'X-CC-Key-ID': 'your-key-id',
    }
)

响应示例

200成功

{
  "code": "0",
  "data": {
    "signGrantToken": "<GRANT_TOKEN_PLACEHOLDER>",
    "signGrantTokenExpireAt": "1784769600000"
  }
}

错误码

HTTP 状态码	code	说明
404	esign_grant_not_found	预授权不存在或不属于当前账户（grantId 有误）
409	esign_grant_token_not_available	Token 尚未就绪。云签经回调 + B2 查询双通道（回调未达时由查询兜底）向 CertCloud 交付；grantId 与 Token 受同一生效门控，刚生效时常为交付在途——按 3~5 秒间隔稍后重试即可。也可能是终端用户尚未完成预授权确认。远超交付窗口（1~2 小时）仍不可得时，携 grantId / willId 联系技术支持
410	esign_grant_gone	预授权已进入终态（已撤销 / 已过期 / 次数耗尽），Token 不再可取。如需继续使用两步轨，重新创建预授权意愿