Authentication

All API requests passed to or from the Operator’s system must be authenticated to prove that they are coming from a trusted source. Add your operator signature to the header of each HTTP request.

Your operator signature is constructed based on information provided by the VeliGames. To start with, you save the information encoded in the signature as a JSON document. Then, you need to convert the contents of the document into a string and, finally, transform all parameters and values into an operator signature using a hash-based authentication code (HMAC).

An example of the operator signature

The signature is prefixed with the operator ID provided by VeliGames. In the following example, the operator ID appears as the OPERATOR_ID placeholder.

Note

For the sake of example, the signature has been shortened; the missing characters have been replaced with ….

{
   "Content-Type":"application/json",
   "signature":"OPERATOR_ID:tapm5+EvNZ5dCCN...N5CdDx0GCfUspxw=="
}
Copy code

Constructing a signature

To be able to construct a valid operator signature, you need to obtain your OPERATOR_ID and a secret key from VeliGames. The OPERATOR_ID is part of the operator signature which is passed in the request header. You need the unique secret key to generate an HMAC.

The signature includes all parameters from the request. Each parameter is specified as the full path.

Create a JSON document

Start by placing all request parameters into a UTF-8 encoded JSON document. Arrange the parameters on separate lines in the ascending (A to Z) alphabetic order. If the full path of a parameter is complex, the components are separated with a colon (:)

<parent_1>:…:<parent_n>:<parameter_name>:<parameter_value>

{
   "brandId": "yourBrand",
   "gameId": "garage",
   "deviceType": "DESKTOP",
   "providerId": "infinity",
   "language": "en",
   "playerId": "PLAYER-uuid",
   "currency": "EUR",
   "country": "UK",
   "sessionId": "550e84...440000",
   "ip": "0.0.0.0"
}
Copy code

Convert the JSON document into a string

The signature is applied to a string constructed based on the JSON document with arranged parameters.

Apply the following changes:

1. Remove the enclosing curly braces “{}” from the JSON document.

2. Replace line breaks between parameters with semicolons (;).

3. Remove quotes (single or double) that delimited string values.

Important

Do not omit empty parameters. The values of such parameters are not represented in any way.

Make sure that you do not accidentally insert whitespace, nulls, or a pair of quotes, such as (“”), to represent missing values.

Correct

brandId:SomeBrand;currency:;country:UK

Incorrect (a missing value for currency is represented with whitespace)**

brandId:SomeBrand;currency: ;country:UK

Compute the signature

The actual signature which is passed in the header of HTTP requests is a base64 HMAC code. The HMAC algorithm implemented for VeliGames uses the SHA512 encryption. This algorithm is available for many programming languages. The following example demonstrates how to to generate an HMAC code from Node.js. Note that the correct HMAC code is only generated with the secret key that the operator must have obtained from VeliGames.

const hmac = crypto.createHmac('sha512', secretKey);
hmac.update(data).digest('base64');
Copy code

When serialized, the hmac variable returns the correct signature that you may pass in the header of your HTTP request. Notice that the signature must be prefixed with the operator ID that you receive from VeliGames. For an operator ID, such as veligames, the HMAC signature encoded as a base64 number would look like this:

veligames:tapm5+EvNZ5dCCN...N5CdDx0GCfUspxw==
Copy code

You may now pass your signature in the header of your HTTP request as the value of the signature parameter. The signature for the operator ID veligames looks as follows:

{
    "Content-Type":"application/json",
    "signature":"veligames:tapm5+EvNZ5dCCN...N5CdDx0GCfUspxw=="
}
Copy code

Testing the signature

VeliGames offers the gen-signature endpoint for testing the correctness of signatures. The SECRET_KEY placeholder refers to the secret key provided by VeliGames. (Stage only)

Path:

https://VELIGAMES_API_URL/unified-api/public/gen-signature?secret=SECRET_KEY’

When using this endpoint, replace the SECRET_KEY with your own secret key and pass the JSON document with actual request parameters. The following example demonstrates how to use the gen-signature endpoint with the curl command.

curl -X 'POST' \
'https://VELIGAMES_API_URL/unified-api/public/gen-signature?secret=SECRET_KEY' \
-H 'accept: */*' \
-H 'Content-Type: application/json' \
-d '{
      "providerId": "your_provider_id",
      "gameId": "OlympianTreasures",
      "language": "en",
      "playerId": "PLAYER-11231...1243",
      "currency": "XAF",
      "deviceType": "DESKTOP",
      "country": "GE",
      "brandId": "yourBrand",
      "sessionId": "6c210f4...48f4406ba",
      "ip": "192.0.2.0"
   }'
Copy code

The response to this request contains the converted string for parameters and values and the generated HMAC base64 signature:

[
   "brandId:yourBrand;country:GE;currency:XAF...sessionId:6c210f4...48f4406ba",
   "FlGw7K/ZXqbh...sNhhZ4xvi2A=="
]
Copy code

Note

The parameters appear in ascending alphabetic order as one concatenated string delimited by semicolons (;). All double quote characters (”) have been removed.