Authentication means

There are 3 different authentication means. Most routes support only one authentication mean.

API key only

This authentication mean is used by routes which do not require a high security level. To use this authentication mean you simply pass your API key in an 'apikey' request header. No session token is returned here.

Example: Assuming your API key is "ABCD":

curl -H "apikey: ABCD" -X GET https://api.jackpot-io.com/v2/stores

Client session

This authentication mean is used by routes which can be called within the client application. To proceed, you must generate a JWT token and pass it to endpoint POST /v2/token. In return you get a session token to be used in subsequent API calls.

The JWT must contain the following fields and be signed with the HS256 algorithm:

  • amount: maximum amount to be spent in the session
  • iat: timestamp in seconds
  • notificationKey: unique key identifying the transaction (generated by the caller)
  • userId: unique ID identifying end user (optional)
  • forceManualConfirm: true/false - Require manual confirmation of the reserved voucher, see below (optional)

Website https://jwt.io/ allows to to decode and check your token, and gives a list of libraries for token signing.

PHP sample code on how to generate JWT:

//composer require firebase/php-jwt
<?php
use \Firebase\JWT\JWT;

$signature = "monApiSignature";
$criteria=array(
      "amount" => 100, 
      "iat" => time(),
      "notificationKey" => "12345"
);
$jwt = JWT::encode($criteria, $signature);
?>

API call example:

curl -d '{"grant_type": "urn:ietf:params:oauth:grant-type:jwt-bearer", "client_id": "<your_client_id>", "assertion": "<the_generated_JWT"}' -H "Content-Type: application/json" -X POST https://api.jackpot-io.com/v2/token

Machine-to-machine (m2m) session

This authentication mean is used by routes which must be called by your server. To use this authentication mean you must provide your API key (as "client_id" field) as well as your client secret.

The client secret is not provided in the administration interface and will be provided to you directly by the Jackpot team. In return you get a session token to be used in subsequent API calls.

API call example:

curl -d '{"grant_type": "client_credentials", "client_id": "<your_client_id>", "client_secret": "<your_client_secret>"}' -H "Content-Type: application/json" -X POST https://api.jackpot-io.com/v2/token