GeekNums开发者文档

鉴权

每个请求都需要四个请求头。密钥既是身份标识,也是签名密钥,不会在请求中明文传输签名以外的内容。

请求头

字段类型说明
X-Api-Keystring必填控制台生成的 API Key,同时用作签名密钥
X-Api-Tsstring必填Unix 毫秒时间戳,与服务器时间相差不超过 5 分钟
X-Api-Noncestring必填16~64 字符随机串,每次请求必须不同
X-Api-Signstring必填Base64(HMAC-SHA256(签名原文, API Key))

签名原文

五段以换行符连接,顺序固定。注意 PATH 含 /api 前缀,带 query 时一并计入且不重排。

1METHOD大写,如 GET / POST
2PATH[?QUERY]含 /api,query 原样
3X-Api-Ts毫秒时间戳
4X-Api-Nonce随机串
5SHA256_HEX(body)无 body 即空串的摘要

五段以换行符连接后,签名 = Base64(HMAC-SHA256(该原文, API Key)),放入 X-Api-Sign。

一个真实例子

五段(换行分隔)
GET
/api/open/v1/tasks?from=0&size=5
1758153600000
9f2c1a7b4e6d8035
e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855

规则

  • 时间戳与服务器时间相差不得超过 5 分钟(双向)。请确保机器时钟已同步。
  • nonce 为 16~64 字符的随机串,每个请求都必须不同。重复使用会被拒绝,这是防重放机制。
  • JSON 请求体参与签名(取其 SHA-256 十六进制)。GET 请求与文件直传使用空字符串的 SHA-256。
  • query 参数按原始顺序计入,不排序、不解码。直接用你实际请求的 URL 即可。

示例代码

# cURL 本身不能算 HMAC,先用 shell 生成签名再发请求
API_KEY="YOUR_API_KEY"
URL="https://api.geeknums.io/api/open/v1/account"
METHOD="GET"
BODY=''

PATH_Q=$(printf '%s' "$URL" | sed -E 's#^https?://[^/]+##')
TS=$(( $(date +%s) * 1000 ))
NONCE=$(head -c16 /dev/urandom | xxd -p)
BODY_HASH=$(printf '%s' "$BODY" | openssl dgst -sha256 -hex | sed 's/^.* //')
SIGN_BASE=$(printf '%s\n%s\n%s\n%s\n%s' "$METHOD" "$PATH_Q" "$TS" "$NONCE" "$BODY_HASH")
SIGN=$(printf '%s' "$SIGN_BASE" | openssl dgst -sha256 -hmac "$API_KEY" -binary | base64)

curl -X "$METHOD" "$URL" \
  -H "X-Api-Key: $API_KEY" \
  -H "X-Api-Ts: $TS" \
  -H "X-Api-Nonce: $NONCE" \
  -H "X-Api-Sign: $SIGN"