Get Access Token
Obtain a JWT access token for accessing other APIs. After obtaining the access token, it must be added to the request headers in order to call any API 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 the cipherText field.
Parameters Before Encryption
info
Use the "Secret KEY" from the integration configuration document and the corresponding secret parameter for this API — do not use 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 Period: The accessToken usually expires after 1 hour and must be obtained again.
- Secure Storage: Store the accessToken securely on the server side; do not expose it on the Operator side.
- Time Synchronization: Ensure the server time is synchronized with the VP server time. Excessive time drift will cause verification failures.
- Nonce Uniqueness: A new nonce value should be used for every request.
- Error Retry: If a 401 error is received, the accessToken should be obtained again.