跳到主要内容

获取 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"

错误响应​

当请求失敗时，会返回对应的错误代码。

错误代码​

状态码说明处理建议
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. 时间同步：确保服务器时间与 VP 服务器时间同步，时间偏差过大会导致验证失敗
  4. Nonce 唯一性：每次请求都应使用新的 nonce 值
  5. 错误重试：如果收到 401 错误，应重新获取 accessToken

相关 API​