Request Security

Every request made to the Topaz Games API must be authenticated to ensure the security and integrity of the communication. This guide outlines the steps to securely make requests to the API and protect your platform from unauthorized access.

Authentication Process

Client Key

The first step in authenticating your requests is obtaining a client key from Topaz Games. The client key is a unique identifier that grants you access to the API and allows you to make authorized requests. To obtain your client key, follow the steps outlined in the Client Registration guide.

Request Signing

Topaz Games API requires each request to be signed using HMAC-SHA1 to ensure that the request is authentic and has not been tampered with. The signature is generated using a combination of request parameters and headers.

Required Headers

• X-Merchant-Id: Your client ID provided by Topaz Games.
• X-Timestamp: The current timestamp in milliseconds.
• X-Nonce: A unique identifier (e.g., UUID) for the request to prevent replay attacks.
• X-Sign: The HMAC-SHA1 signature of the request.

Steps to Generate the Signature

1. Collect Request Data: Gather all the data that will be sent in the request, including both query parameters and headers (excluding X-Sign).
2. Merge Parameters and Headers: Combine the request data and required headers into a single object or array.
3. Sort the Parameters: Sort the combined parameters alphabetically by their keys to ensure consistency.
4. Create a Query String: Convert the sorted parameters into a URL-encoded query string.
5. Generate the Signature: Use HMAC-SHA1 to hash the query string using your client_key as the secret key.
6. Include the Signature in the Request: Add the generated signature to the X-Sign header.

Example Implementation

Below are examples of how to implement the request signing process in both JavaScript and PHP.

Node Example

const axios = require('axios');
const CryptoJS = require('crypto-js');
const { v4: uuidv4 } = require('uuid');

async function createGameSession() {
    const TOPAZ_ID = process.env.TOPAZ_ID;
    const TOPAZ_KEY = process.env.TOPAZ_KEY;
    const TOPAZ_URL = 'https://api.topaz-games.com/game/createGameSession';

    const timestamp = Date.now();
    const nonce = uuidv4();

    const data = {
        game_uuid: 'your_game_uuid',
        player_id: 'player123',
        player_name: 'JohnDoe',
        currency: 'USD',
        session_id: 'session123',
        language: 'en',
        play_money: false,
        player_balance: 1000,
        client_id: TOPAZ_KEY,
    };

    const mergedParams = {
        ...data,
        'X-Merchant-Id': String(TOPAZ_ID),
        'X-Timestamp': timestamp,
        'X-Nonce': nonce,
    };

    // Sort the parameters alphabetically
    const sortedParams = Object.keys(mergedParams)
        .sort()
        .reduce((acc, key) => {
            acc[key] = mergedParams[key];
            return acc;
        }, {});

    // Create a URL-encoded query string
    const queryString = new URLSearchParams(sortedParams).toString();

    // Generate the HMAC-SHA1 signature
    const sign = CryptoJS.HmacSHA1(queryString, TOPAZ_KEY).toString();

    try {
        const response = await axios.get(TOPAZ_URL, {
            headers: {
                'X-Merchant-Id': TOPAZ_ID,
                'X-Timestamp': timestamp,
                'X-Nonce': nonce,
                'X-Sign': sign,
                'Content-Type': 'application/x-www-form-urlencoded',
            },
            params: data,
        });

        console.log('Game session URL:', response.data.url);
    } catch (error) {
        console.error('Error creating game session:', error);
    }
}

createGameSession();

PHP Example

function createGameSession() {
    $TOPAZ_ID = getenv('TOPAZ_ID');
    $TOPAZ_KEY = getenv('TOPAZ_KEY');
    $TOPAZ_URL = getenv('TOPAZ_URL');

    $timestamp = round(microtime(true) * 1000);
    $nonce = uniqid();

    $data = array(
        'game_uuid' => 'your_game_uuid',
        'player_id' => 'player123',
        'player_name' => 'JohnDoe',
        'currency' => 'USD',
        'session_id' => 'session123',
        'language' => 'en',
        'play_money' => false,
        'player_balance' => 1000,
        'client_id' => $TOPAZ_KEY,
    );

    $mergedParams = array_merge($data, array(
        'X-Merchant-Id' => $TOPAZ_ID,
        'X-Timestamp' => $timestamp,
        'X-Nonce' => $nonce,
    ));

    // Sort the parameters alphabetically
    ksort($mergedParams);

    // Create a URL-encoded query string
    $queryString = http_build_query($mergedParams);

    // Generate the HMAC-SHA1 signature
    $sign = hash_hmac('sha1', $queryString, $TOPAZ_KEY);

    $headers = array(
        'X-Merchant-Id: ' . $TOPAZ_ID,
        'X-Timestamp: ' . $timestamp,
        'X-Nonce: ' . $nonce,
        'X-Sign: ' . $sign,
        'Content-Type: application/x-www-form-urlencoded',
    );

    $queryData = http_build_query($data);

    $ch = curl_init();
    curl_setopt($ch, CURLOPT_URL, $TOPAZ_URL . '?' . $queryData);
    curl_setopt($ch, CURLOPT_HTTPGET, true);
    curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

    $response = curl_exec($ch);
    if ($response === false) {
        echo 'Error creating game session: ' . curl_error($ch);
    } else {
        $responseData = json_decode($response, true);
        echo 'Game session URL: ' . $responseData['url'];
    }

    curl_close($ch);
}

createGameSession();