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 integration configuration document and the corresponding API's secret parameter should be 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 Expiration: accessToken usually expires after 1 hour and needs to be re-obtained.
- Secure Storage: Please store the accessToken securely on the server-side; do not expose it on the Operator.
- Time Synchronization: Ensure server time is synchronized with VP server time; excessive time deviation will lead to authentication failure.
- Nonce Uniqueness: Each request should use a new nonce value.
- Error Retries: If a 401 error is received, accessToken should be re-obtained.