Авторизация запросов¶

Все запросы между агентом и платформой защищены с помощью криптографической подписи на основе HMAC SHA-256. Это обеспечивает безопасность и целостность данных.

Авторизация запросов к платформе¶

Когда агент отправляет запрос к платформе, необходимо подписать запрос с помощью API токена.

Алгоритм подписи¶

Подготовка данных¶

Все данные запроса должны быть в JSON формате в теле запроса (body)
Данные должны быть отсортированы по ключам в алфавитном порядке (для консистентности)

Генерация подписи¶

Преобразовать отсортированные данные в JSON строку
Вычислить HMAC SHA-256 подпись используя API токен как секретный ключ
Подпись передается в HTTP заголовке X-Signature

Обязательные поля в запросе¶

agent_id (integer) - ID агента
timestamp (integer) - Unix timestamp запроса (в секундах)

Формат запроса¶

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

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

Пример генерации подписи¶

<?php

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

// Сортируем данные по ключам
ksort($data);

// Преобразуем в JSON
$jsonData = json_encode($data);

// Генерируем подпись
$apiToken = 'your-api-token-here';
$signature = hash_hmac('sha256', $jsonData, $apiToken);

// Отправляем запрос
$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);

Таймаут запросов¶

Запросы имеют ограничение по времени жизни. Если разница между текущим временем и timestamp в запросе превышает 300 секунд (5 минут), запрос будет отклонен.

Важно

Всегда используйте актуальное время сервера для генерации timestamp.

Возможные коды ошибок¶

signature_required (401) - отсутствует заголовок X-Signature
invalid_signature (403) - неверная подпись
agent_not_found (404) - агент с указанным agent_id не найден
api_token_not_found (404) - у агента не настроен API токен

Авторизация коллбеков от платформы¶

Когда платформа отправляет коллбек агенту, запрос также подписывается. Агент должен проверить подпись перед обработкой запроса.

Формат коллбека¶

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
}

Алгоритм проверки подписи¶

Извлечь подпись¶

Подпись находится в HTTP заголовке X-Signature
Извлечь подпись из заголовка запроса

Подготовка данных¶

Взять все данные из тела запроса (JSON)
Отсортировать по ключам в алфавитном порядке

Генерация ожидаемой подписи¶

Преобразовать отсортированные данные в JSON строку
Вычислить HMAC SHA-256 используя ваш API токен

Сравнение подписей¶

Сравнить полученную подпись с ожидаемой (используйте безопасное сравнение, например hash_equals в PHP)

Пример проверки подписи¶

<?php

function verifyCallbackSignature(array $data, string $signature, string $apiToken): bool
{
    // Проверяем наличие подписи
    if (empty($signature)) {
        return false;
    }

    // Сортируем данные
    ksort($data);

    // Преобразуем в JSON
    $jsonData = json_encode($data);

    // Генерируем ожидаемую подпись
    $expectedSignature = hash_hmac('sha256', $jsonData, $apiToken);

    // Безопасное сравнение
    return hash_equals($expectedSignature, $signature);
}

// Использование
$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;
}

// Обработка коллбека
// ...

Важно

Всегда проверяйте подпись перед обработкой коллбека

Получение API токена¶

API токен выдается менеджером платформы при настройке вашего аккаунта. Если у вас нет токена или вы хотите его перегенерировать, обратитесь к вашему менеджеру.