验证¶
POST /api/v1/workspace/accesskey/verify
概述¶
验证当前 API Key 或 AccessKey SK token
Body 请求参数¶
| 参数名 | 类型 | 必选 | 说明 |
|---|---|---|---|
| version | any | 新版 SK token 协议版本；传 20260617 时只需 timestamp，不再要求 nonce/signature 例子: 20260617 允许为空: True |
|
| timestamp | integer | Y | 毫秒时间戳，服务端只接受 10 分钟内的请求 例子: 1711111111000 允许为空: False |
| nonce | string | 旧版签名协议字段；客户端生成的随机字符串，长度 16-128，只允许字母、数字、.、_、:、- 例子: 2b7c3a9e4f6545b7aef09a23f9e0c001 允许为空: True |
|
| signature | string | 旧版签名协议字段；使用 sk 对固定签名串计算得到的 64 位 HMAC-SHA256 hex 小写字符串 例子: 3b4d0b1e8f3b6d2d9f30e6f2b7f08f0b2c4f0e9f4f9a6d6c6c7a8b9c0d1e2f3a 允许为空: True |
参数补充说明¶
该接口用于验证当前请求头 DF-API-KEY 中的 sk。验证通过后返回当前 API Key 的所属账号、角色和权限信息，响应中不返回 ak/sk 字段。
version=20260617 新版协议¶
- 请求头
DF-API-KEY必须传当前 OpenAPI 调用使用的sk。 - 请求体传
version=20260617和timestamp。 timestamp为毫秒时间戳，服务端只接受与当前时间相差不超过 10 分钟的请求。- 新版不再要求
nonce和signature。 version建议传数字20260617，服务端兼容字符串"20260617"。
旧版签名算法¶
- 请求头
DF-API-KEY必须传当前 OpenAPI 调用使用的sk。 - 未传
version=20260617时，请求体继续按旧版传timestamp、nonce、signature。 timestamp为毫秒时间戳，服务端只接受与当前时间相差不超过 10 分钟的请求。nonce为客户端生成的随机字符串，长度 16-128，只允许字母、数字、.、_、:、-；同一 API Key 记录的同一个nonce在 10 分钟内只能使用一次。- 签名算法固定为
HMAC-SHA256，输出 64 位 hex 小写字符串。 - 签名串固定为：
ak=<ak>&method=POST&nonce=<nonce>&path=/api/v1/workspace/accesskey/verify×tamp=<timestamp>。 - 上述
<ak>为调用方本地持有、需要验证是否与当前sk配对的ak，不放入请求头或请求体。 signature = HMAC-SHA256-HEX(secret=<sk>, message=<签名串>)。
请求例子¶
curl 'https://openapi.guance.com/api/v1/workspace/accesskey/verify' \
-H 'DF-API-KEY: <sk>' \
-H 'Content-Type: application/json;charset=UTF-8' \
--data-raw '{"version": 20260617, "timestamp": 1711111111000}' \
--compressed
旧版签名调用：
curl '<Endpoint>/api/v1/workspace/accesskey/verify' \
-H 'DF-API-KEY: <sk>' \
-H 'Content-Type: application/json;charset=UTF-8' \
--data-raw '{"timestamp": 1711111111000, "nonce": "2b7c3a9e4f6545b7aef09a23f9e0c001", "signature": "3b4d0b1e8f3b6d2d9f30e6f2b7f08f0b2c4f0e9f4f9a6d6c6c7a8b9c0d1e2f3a"}' \
--compressed
响应¶
{
"code": 200,
"content": {
"uuid": "wsak_xxx",
"name": "func-ak",
"workspaceUUID": "wksp_xxx",
"createdWay": "manual",
"accountUUID": "",
"accountInfo": null,
"effectiveAccountUUID": "wsak_xxx",
"roles": [
{
"uuid": "readOnly",
"name": "只读成员"
}
],
"permissions": [
"data.query"
],
"rolePermissions": {
"readOnly": [
"data.query"
]
}
},
"errorCode": "",
"message": "",
"success": true,
"traceId": "TRACE-XXXX"
}