Authentication Overview

VertexPlay API uses a multi-layer authentication mechanism to ensure the security of API requests.

Verification Flow

request Headers

All API requests must include the following headers:

Authentication Request (/v2/auth)

Header	Type	Required	Description
Content-Type	string	Yes	Must be application/json
x-agentid	string	Yes	Agent ID
x-timestamp	string	Yes	Unix timestamp (milliseconds)
x-nonce	string	Yes	32-character random string (used to prevent replay attacks)
x-signature	string	Yes	SHA256 signature

Other API Requests

Header	Type	Required	Description
Authorization	string	Yes	Bearer token, format: Bearer {accessToken}
Content-Type	string	Yes	Must be application/json
x-agentid	string	Yes	Agent ID
x-timestamp	string	Yes	Unix timestamp (milliseconds)
x-nonce	string	Yes	32-character random string
x-signature	string	Yes	SHA256 signature

Signature Generation

The signature is generated using the SHA256 algorithm to ensure the integrity and authenticity of the request.

Signature Generation Steps

1. Prepare the signature string: Concatenate the following parameters in order

   agentId + timestamp + nonce + requestBody

2. Generate the signature: Use the SHA256 algorithm

   signature = SHA256(signatureString)

3. Add to request headers: Place the generated signature in the x-signature header

Node.js Example

const crypto = require('crypto');

function generateSignature(agentId, timestamp, nonce, requestBody) {

  const bodyString = JSON.stringify(requestBody);
  
  const signatureString = agentId + timestamp + nonce + bodyString;
  
  const signature = crypto
    .createHash('sha256')
    .update(signatureString)
    .digest('hex');
  
  return signature;
}

const agentId = 'integratorNBTest04';
const timestamp = Date.now().toString();
const nonce = crypto.randomBytes(16).toString('hex');
const requestBody = {
  cipherText: 'G0ZMDELeJwx+7JcIfIFO...'
};

const signature = generateSignature(agentId, timestamp, nonce, requestBody);

Python Example

import hashlib
import json
import time
import secrets

def generate_signature(agent_id, timestamp, nonce, request_body):
    body_string = json.dumps(request_body, separators=(',', ':'))
    
    signature_string = agent_id + timestamp + nonce + body_string
    
    signature = hashlib.sha256(
        signature_string.encode('utf-8')
    ).hexdigest()
    
    return signature

agent_id = 'integratorNBTest04'
timestamp = str(int(time.time() * 1000))
nonce = secrets.token_hex(16)
request_body = {
    'cipherText': 'G0ZMDELeJwx+7JcIfIFO...'
}

signature = generate_signature(agent_id, timestamp, nonce, request_body)

Data Encryption

All sensitive data in requests use AES-256-GCM encryption, and responses are in plain JSON format.

Encryption Format

{
  "cipherText": "ivBase64(16字元) + authTagBase64(24字元) + encryptedDataBase64"
}

Encryption Parameters

• Algorithm: AES-256-GCM
• Key Length: 256 bits (32 bytes)
• IV Length: 96 bits (12 bytes)
• Authentication Tag Length: 128 bits (16 bytes)

cipherText Structure

cipherText consists of three parts, all encoded using Base64:

1. IV (Initialization Vector)

   • Length: 12 bytes
   • After Base64 encoding: 16 characters
   • Position: cipherText[0:16]

2. Auth Tag (Authentication Tag)

   • Length: 16 bytes
   • After Base64 encoding: 24 characters
   • Position: cipherText[16:40]

3. Encrypted Data

   • Length: Variable, depending on the original data
   • Base64 encoded
   • Position: cipherText[40:]

Decryption Example (Node.js)

const crypto = require('crypto');

const AES_ALGORITHM = 'aes-256-gcm';

/**
 * Decrypt cipherText
 * @param {string} key - AES key (hex format)
 * @param {string} cipherText - Encrypted text
 * @returns {Object} - Decrypted JSON object
 */
function symmetricDecrypt(key, cipherText) {
  try {
    const aesKey = Buffer.from(key, 'hex');

    // Split iv, authTag, and encrypted data from cipherText
    const ivLength = 16; // 12 bytes after Base64 encoding
    const authTagLength = 24; // 16 bytes after Base64 encoding

    const ivBase64 = cipherText.substring(0, ivLength);
    const authTagBase64 = cipherText.substring(ivLength, ivLength + authTagLength);
    const encryptedData = cipherText.substring(ivLength + authTagLength);

    const aesIv = Buffer.from(ivBase64, 'base64');
    const authTag = Buffer.from(authTagBase64, 'base64');

    // Create decipher
    const decipher = crypto.createDecipheriv(AES_ALGORITHM, aesKey, aesIv);
    decipher.setAuthTag(authTag); // Set authentication tag; GCM verifies integrity automatically

    // Decrypt
    let decrypted = decipher.update(encryptedData, 'base64', 'utf8');
    decrypted += decipher.final('utf8'); // Throws an error if authTag verification fails

    return JSON.parse(decrypted);
  } catch (e) {
    throw new Error(`Symmetric Decryption Failed: ${e.message}`);
  }
}

// Usage example
const key = 'your-32-byte-hex-key'; // 64 hex characters = 32 bytes
const cipherText = 'G0ZMDELeJwx+7JcI...'; // Full cipherText

try {
  const decryptedData = symmetricDecrypt(key, cipherText);
  console.log('Decrypted data:', decryptedData);
} catch (error) {
  console.error('Decryption error:', error.message);
}

Encryption Example (Node.js)

/**
 * Encrypt data
 * @param {string} key - AES key (hex format)
 * @param {Object} data - JSON object to be encrypted
 * @returns {string} - Encrypted cipherText
 */
function symmetricEncrypt(key, data) {
  try {
    const aesKey = Buffer.from(key, 'hex');
    
    // Generate random IV (12 bytes)
    const aesIv = crypto.randomBytes(12);
    
    // Create cipher
    const cipher = crypto.createCipheriv(AES_ALGORITHM, aesKey, aesIv);
    
    // Encrypt data
    const jsonString = JSON.stringify(data);
    let encrypted = cipher.update(jsonString, 'utf8', 'base64');
    encrypted += cipher.final('base64');
    
    // Get authentication tag (16 bytes)
    const authTag = cipher.getAuthTag();
    
    // Combine cipherText: ivBase64 + authTagBase64 + encryptedData
    const cipherText = aesIv.toString('base64') + 
                       authTag.toString('base64') + 
                       encrypted;
    
    return cipherText;
  } catch (e) {
    throw new Error(`Symmetric Encryption Failed: ${e.message}`);
  }
}

// Usage example
const data = {
  username: 'player001',
  amount: 100
};

const cipherText = symmetricEncrypt(key, data);
console.log('Encrypted cipherText:', cipherText);

Error Handling

Authentication Error Codes

Code	Description
84	Decryption Failed - Possible invalid key or corrupted data
83	Authentication Failed - Signature verification failed or invalid parameters

Error Response Format

{
  "code": 83,
  "message": "Signature verification failed",
  "logUUID": "6589bf8d-fe74-48bd-841a-71bf8f848f86"
}

Security Recommendations

1. Protect the Secret Key: Never store the Secret Key in client-side code or any public location
2. Use HTTPS: All API requests must be transmitted over HTTPS
3. Timestamp Validation: Ensure the timestamp is within an acceptable range (recommended: ±1 minute)
4. Nonce Uniqueness: Use a unique nonce for each request to prevent replay attacks
5. Token Management: Refresh the accessToken regularly; do not reuse the same token for long periods
6. Error Handling: Handle authentication errors properly to avoid leaking sensitive information

Next Steps

Learn how to Get Access Token to start using the API.