跳到主要内容

获取 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，用于问题排查和日誌查询

错误响应​

{
  "code": 83,
  "message": "认证失敗：签章验证错误",
  "logUUID": "24cdc3b9-9fe8-44de-8391-a96863e46954"
}

注意事项​

  1. Token 有效期：accessToken 通常在 1 小时后过期，需要重新获取
  2. 安全存儲：请在服务器端安全存儲 accessToken，不要在客户端暴露
  3. 时间同步：确保服务器时间与 VP 服务器时间同步，时间偏差过大会导致验证失敗
  4. Nonce 唯一性：每次请求都应使用新的 nonce 值
  5. 错误重试：如果收到 401 错误，应重新获取 accessToken

注意事项​

  1. Token 有效期：accessToken 通常在 1 小时后过期，需要重新获取
  2. 安全存儲：请在服务器端安全存儲 accessToken，不要在客户端暴露
  3. 错误重试：如果收到 401 错误，应重新获取 accessToken

相关 API​