身份認證與安全

API 密鑰安全機制、請求標頭簽名（HMAC-SHA256）與權限範圍（Scopes）。

Pinnacle API 採用金融級安全規範。所有請求均需攜帶合法的 Bearer Token，敏感業務寫入需提供 HMAC-SHA256 請求標頭簽名與時間戳防重放機制。

必要 HTTP 請求標頭

所有發往 Pinnacle API 網關的請求必須包含以下標準標頭：

標頭名稱 (Header)	類型	必填	說明與格式
Authorization	String	必填	Bearer 認證格式，例如: Bearer sec_live_9a8b7c6d5e4f...
Content-Type	String	必填	統一為 application/json; charset=utf-8
X-Pinnacle-Timestamp	Integer	必填	當前 UTC 毫秒級時間戳，伺服器允許 ±300 秒時間偏差
X-Pinnacle-Signature	String	建議	基於 Secret Key 生成的 HMAC-SHA256 簽名摘要，防竄改保護
Idempotency-Key	String	條件	變更類請求（POST/PUT/DELETE）必填，防止因網絡超時重複扣費或創建

HMAC-SHA256 簽名演算法規範

簽名原始字串 (String to Sign) 由 HTTP 方法、請求路徑、時間戳及請求主體哈希拼接而成：

簽名拼接格式公式

StringToSign = HTTP_METHOD + "\n" +
               REQUEST_PATH + "\n" +
               TIMESTAMP + "\n" +
               SHA256_HEX(REQUEST_BODY)

Signature = HMAC_SHA256_HEX(API_SECRET, StringToSign)

多後端語言簽名與發起請求完整示例

以下演示如何使用 Python、Go、Node.js、Java 及 cURL 構建帶有簽名與認證標頭的 POST 請求：

發起鑑權請求範例

curl -X POST "https://api.pinnacle-advisory.vg/v1/analytics/jobs" \
  -H "Authorization: Bearer sec_live_9a8b7c6d5e4f" \
  -H "Content-Type: application/json" \
  -H "X-Pinnacle-Timestamp: 1774944000000" \
  -H "X-Pinnacle-Signature: 8f9b2d3c...e5a1" \
  -H "Idempotency-Key: idemp_9918237192" \
  -d '{"task_type":"forecasting","dataset_id":"ds_7781"}'

必要 HTTP 請求標頭

HMAC-SHA256 簽名演算法規範

多後端語言簽名與發起請求完整示例

發起鑑權請求範例

On this page