Get Access Token
Obtain a JWT access token for accessing other APIs.
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
{
"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"
}
ResponseFieldDescription
| 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 typically expires after 1 hour and needs to be re-acquired
- 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 the VP server time; large time discrepancies will lead to authentication failure
- Nonce Uniqueness: A new nonce value should be used for each request
- Error Retry: If a 401 error is received, accessToken should be re-acquired