跳至主要内容

獲取 Access Token

獲取用於訪問其他 API 的 JWT access token。

API 信息​

  • 端點：POST /v2/auth
  • 認證：簽章驗證（不需要 Bearer token）
  • 加密：請求使用 AES-256-GCM 加密，響應為明文 JSON

請求​

請求標頭​

POST /v2/auth HTTP/1.1
Host: api.example.com
Content-Type: application/json
x-agentid: integratorNBTest04
x-timestamp: 1769745532582
x-nonce: 4ff08bc2a45c6b38068dbcd24296a25b
x-signature: 904e97bee2589b93e9747eed0346c68b23d8ff8b568dabaf4b94a5e89093df67

請求參數​

請求參數需要加密後放入 cipherText 欄位。

加密前的參數​

{
  "agentId": "integratorNBTest01",
  "secret": "examplesecret=="
}

加密後的請求體​

{
  "cipherText": "G0ZMDELeJwx+7JcIfIFOLJjkSzANPu6krGM2uw==bDUB6MvLbggJM4Df28x/41LlgIPDqPBBAylkqTdB0I78haWOdi6jV8JXAi0iL8JHq/cCPlj39Apt/I9hDNII3SBb0IZMg+qGN3pH3zExydFZSLXwErOa/6KzGMHukRkqHjdFzQ=="
}
欄位類型必填說明
agentIdstring是營運商代理 ID
secretstring是營運商密鑰

響應​

成功響應​

響應數據為明文 JSON 格式。

{
  "code": 0,
  "message": "No error.",
  "data": {
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhZ2VudElkIjoiaW50ZWdyYXRvck5CVGVzdDA0IiwiaWF0IjoxNzY5NzQ1NTMyLCJleHAiOjE3Njk3NDkxMzJ9.abc123def456...",
    "expiresIn": 3600,
    "tokenType": "Bearer"
  },
  "logUUID": "24cdc3b9-9fe8-44de-8391-a96863e46954"
}
欄位類型說明
accessTokenstringJWT access token，用於後續 API 請求
expiresInnumberToken 有效期（秒），通常為 3600 秒（1 小時）
tokenTypestringToken 類型，固定為 "Bearer"
logUUIDstring請求追蹤 ID，用於問題排查和日誌查詢

錯誤響應​

當請求失敗時，會返回對應的錯誤代碼。

錯誤代碼​

狀態碼說明處理建議
10Agent code was not found or block請確認 agentId 和 secret 是否正確，或聯繫技術支援檢查代理商狀態
11Parameters error請確認請求參數完整且格式正確
83Signature verification failed請檢查簽章計算是否正確，確認時間戳和 nonce 是否一致
84Encryption failed請檢查加密方式和金鑰是否正確

錯誤響應範例​

{
  "code": 10,
  "message": "Agent code was not found or block",
  "logUUID": "24cdc3b9-9fe8-44de-8391-a96863e46954"
}
{
  "code": 11,
  "message": "Parameters error",
  "logUUID": "24cdc3b9-9fe8-44de-8391-a96863e46954"
}

注意事項​

  1. Token 有效期：accessToken 通常在 1 小時後過期，需要重新獲取
  2. 安全存儲：請在服務器端安全存儲 accessToken，不要在客戶端暴露
  3. 錯誤重試：如果收到 401 錯誤，應重新獲取 accessToken

相關 API​