GeekNumsDeveloper Docs

Authentication

Every request carries four headers. Your key is both the identity and the signing secret; nothing but the signature derived from it travels in the request.

Headers

FieldTypeDescription
X-Api-KeystringrequiredThe API key from your console; also the signing secret
X-Api-TsstringrequiredUnix milliseconds, within 5 minutes of server time
X-Api-NoncestringrequiredRandom string of 16-64 chars, unique per request
X-Api-SignstringrequiredBase64(HMAC-SHA256(string-to-sign, API key))

String to sign

Five segments joined by newlines, in a fixed order. Note that PATH includes the /api prefix, and the query string is included as-is when present.

1METHODUppercase, e.g. GET / POST
2PATH[?QUERY]Includes /api; query verbatim
3X-Api-TsMilliseconds
4X-Api-NonceRandom string
5SHA256_HEX(body)Digest of empty string when no body

Join the five segments with newlines, then X-Api-Sign = Base64(HMAC-SHA256(that string, API key)).

A concrete example

Five segments (newline separated)
GET
/api/open/v1/tasks?from=0&size=5
1758153600000
9f2c1a7b4e6d8035
e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855

Rules

  • The timestamp must be within 5 minutes of server time, in either direction. Keep your machine clock in sync.
  • The nonce is a random string of 16-64 characters and must differ on every request. Reuse is rejected — this is the replay protection.
  • A JSON body is signed via its SHA-256 hex digest. GET requests and direct file uploads use the SHA-256 of an empty string.
  • Query parameters are included in their original order — not sorted, not decoded. Use the URL exactly as you request it.

Sample code

# 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"