Request authorization

All requests between an agent and the platform are protected with a cryptographic signature based on HMAC SHA-256. This ensures security and data integrity.

Signing requests to the platform

When an agent sends a request to the platform, the request must be signed using the API token.

Signature algorithm

Data preparation

• All request data must be sent as JSON in the request body
• The data must be sorted by keys in alphabetical order (for consistency)

Signature generation

• Convert the sorted data to a JSON string
• Compute an HMAC SHA-256 signature using the API token as the secret key
• Send the signature in the X-Signature HTTP header

Required fields

• agent_id (integer): agent ID
• timestamp (integer): Unix timestamp of the request (seconds)

Request format

POST /api/games/{endpoint} HTTP/1.1
Host: api.example.com
Content-Type: application/json
X-Signature: {подпись}

{
  "agent_id": 1,
  "timestamp": 1640995200,
  ...другие поля...
}

Signature generation example

<?php

$data = [
    'agent_id' => 1,
    'timestamp' => time(),
    'game_id' => 123,
    'player_id' => 'player_123'
];

// Sort data by keys
ksort($data);

// Convert to JSON
$jsonData = json_encode($data);

// Generate signature
$apiToken = 'your-api-token-here';
$signature = hash_hmac('sha256', $jsonData, $apiToken);

// Send request
$ch = curl_init('https://api.example.com/api/games/get_game_link');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $jsonData);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Content-Type: application/json',
    'X-Signature: ' . $signature
]);
$response = curl_exec($ch);
curl_close($ch);

Request timeout

Requests have a limited lifetime. If the difference between the current time and the timestamp in the request exceeds 300 seconds (5 minutes), the request will be rejected.

Important

Always use accurate server time when generating timestamp.

Possible error codes

• signature_required (401): missing X-Signature header
• invalid_signature (403): invalid signature
• agent_not_found (404): agent with the specified agent_id was not found
• api_token_not_found (404): the agent has no API token configured

Verifying platform callbacks

When the platform sends a callback to the agent, the request is also signed. The agent must verify the signature before processing the request.

Callback format

POST /callback HTTP/1.1
Host: your-domain.com
Content-Type: application/json
X-Signature: {подпись}

{
  "agent_id": 1,
  "session_id": "session-uuid",
  "player_id": "player_123",
  "type": "makeBet",
  "bet": 10.50,
  "win": 25.00
}

Signature verification algorithm

Extract the signature

• The signature is in the X-Signature header
• Extract the signature from the request headers

Prepare data

• Take all data from the request body (JSON)
• Sort by keys in alphabetical order

Generate the expected signature

• Convert the sorted data to a JSON string
• Compute HMAC SHA-256 using your API token

Compare signatures

• Compare the received signature with the expected one (use constant-time comparison, e.g. hash_equals in PHP)

Signature verification example

<?php

function verifyCallbackSignature(array $data, string $signature, string $apiToken): bool
{
    // Ensure signature is present
    if (empty($signature)) {
        return false;
    }

    // Sort data
    ksort($data);

    // Convert to JSON
    $jsonData = json_encode($data);

    // Generate expected signature
    $expectedSignature = hash_hmac('sha256', $jsonData, $apiToken);

    // Constant-time comparison
    return hash_equals($expectedSignature, $signature);
}

// Usage
$callbackData = json_decode(file_get_contents('php://input'), true);
$signature = $_SERVER['HTTP_X_SIGNATURE'] ?? '';
$apiToken = 'your-api-token-here';

if (!verifyCallbackSignature($callbackData, $signature, $apiToken)) {
    http_response_code(403);
    echo json_encode(['error' => 'Invalid signature']);
    exit;
}

// Handle callback
// ...

Important

Always verify the signature before processing a callback

Getting an API token

The API token is issued by the platform manager when your account is set up. If you don’t have a token or want to regenerate it, contact your platform manager.