Get Access Token
Obtain a JWT access token for accessing other APIs. After obtaining the access token, it must be added to the Headers to call APIs other than auth.
API Information
- URL：
POST /v2/auth - Authentication：Signature-based authentication (Bearer token not required)
- Encryption：Requests are encrypted using AES-256-GCM; responses are returned as plaintext JSON
request
Request Headers
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
Request Parameters
Request parameters need to be encrypted and placed in cipherText Field。
Parameters Before Encryption
info
The "Secret KEY" in the connection configuration document and the secret parameter corresponding to that API are used, not the "API KEY".
{
"agentId": "integratorNBTest01",
"secret": "examplesecret=="
}
Encrypted Request Body
{
"cipherText": "G0ZMDELeJwx+7JcIfIFOLJjkSzANPu6krGM2uw==bDUB6MvLbggJM4Df28x/41LlgIPDqPBBAylkqTdB0I78haWOdi6jV8JXAi0iL8JHq/cCPlj39Apt/I9hDNII3SBb0IZMg+qGN3pH3zExydFZSLXwErOa/6KzGMHukRkqHjdFzQ=="
}
| Field | Type | Required | Description |
|---|---|---|---|
agentId | string | Yes | Agent ID |
secret | string | Yes | Operator Secret Key |
Response
Success Response
Response data is in plain JSON format.
{
"code": 0,
"message": "No error.",
"data": {
"accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhZ2VudElkIjoiaW50ZWdyYXRvck5CVGVzdDA0IiwiaWF0IjoxNzY5NzQ1NTMyLCJleHAiOjE3Njk3NDkxMzJ9.abc123def456...",
"expiresIn": 3600,
"tokenType": "Bearer"
},
"logUUID": "24cdc3b9-9fe8-44de-8391-a96863e46954"
}
Response Field Description
| Field | Type | Description |
|---|---|---|
data.accessToken | string | JWT access token, used for subsequent API requests |
data.expiresIn | number | Token expiration (seconds), usually 3600 seconds (1 hour) |
data.tokenType | string | Token Type，fixed to "Bearer" |
Error Response
When the request fails, the corresponding error code will be returned.
Error Codes
| Code | Description | Handling Suggestion |
|---|---|---|
| 10 | Agent code was not found or block | Please verify if agentId and secret are correct, or contact customer support team to check the agent status |
| 11 | Parameters error | Please ensure the request parameters are complete and correctly formatted |
| 83 | Signature verification failed | Please check if the signature calculation is correct, and confirm that the timestamp and nonce are consistent |
| 84 | Encryption failed | Please check if the encryption method and key are correct |
Error Response Example
{
"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"
}
Important Notes
- Token Validity: accessToken usually expires after 1 hour and needs to be re-obtained
- Secure Storage: Please store accessToken securely on the server-side, do not expose it on the Operator.
- Time Synchronization: Ensure server time is synchronized with VP server time; large time discrepancies will lead to authentication failure.
- Nonce Uniqueness: Each request should use a new nonce value
- Error Retry: If a 401 error is received, accessToken should be re-obtained