{"info":{"_postman_id":"e28f6e64-c8e0-f2ac-67be-58854e4ca203","name":"Freeplay API","description":"

Introduction

This API offers the possibility to create Freeplay tokens to selected users.

Request

Our server will use JSON as the request body format to be consistent with responses.

Response format

Responses will always be in JSON format.

Authentication

All endpoints in this API requires authentication in order to be accessed.

Authentication is HMAC-signature based.\nUpon registering as a partner with Colossus Bets, you'll receive an api_auth_key and an api_auth_secret.

Please follow the steps below to sign your requests.

Request Headers

There are some important headers that needs to be provided in all your requests:

Date: this is the HTTP timestamp of the request in the RFC 1123/2822 Internet Standard. For security reasons, our API will reject the request when the HTTP timestamp is too much in the past (currently set to 15 minutes max).\nValue example: Mon, 23 Jan 1984 03:29:56 GMT.
\n
Authorization: this is the header that will contain the HMAC signature. The format will be APIAuth-HMAC-SHA256 {{api_auth_key}}:{{signature}}. You'll need to substitute api_auth_key and signature. The former will be provided by us while the latter will need to be calculated (see below in Signature Generation paragraph).
\n
(Optional) Content-MD5: this is the standard header which is the Base64 encoding of the MD5 hash of the request body. It's optional in case of an empty body or a GET request.
\n
(Optional) Content-Type: this is the standard header which will tell the api how to read the request body. It's optional in case of an empty body or a GET request.
\n

Signature Generation

In order to calculate the signature, you'll first need to generate the canonical string. The format for it is the following:

{{HTTP_METHOD}},[Content-Type],[Content-MD5],{{RequestURI}},{{Date}}

HTTP_METHOD: this is the HTTP Method of the request, uppercase. Can be GET, POST, DELETE or any other HTTP method.
RequestURI: this is the path part of your request URL, including the querystring parameters.
Content-Type, Content-MD5 and Date: these are the same values of the 3 headers with the same name, if present.

The elements between {{ }} are mandatory, while the ones between [ ] are optional. All commas are mandatory, even when an element is missing.

Once you calculated the canonical string based on the request, you can proceed calculating the signature from it. This can be achieved with the following 2 steps:

Calculate the SHA256 HMAC hash of the canonical string using your api_auth_secret (provided by us).
Encode the resulting hash using Base64 encoding.

Example

We'll now guide you through an example for a request authentication.

Let's assume Colossus Bets provided you with the following details:

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

Variable	Value
`api_auth_key`	api_key
`api_auth_secret`	api_secret

Let's assume that for this test we want to call the POST /F2PConsole/api/FreeToPlay/GiveTokensToUsers endpoint and the body of the request will be something like:

[\n    {\n        \"user_id\" : \"john23\",\n        \"plays\" : \"2\"\n    },\n    {\n        \"user_id\" : \"amy27\",\n        \"plays\" : \"1\"\n    },\n    {\n        \"user_id\" : \"2376890\",\n        \"plays\" : \"2\"\n    }\n]\n

We will then calculate the content-MD5 header, from the body (y1OKcElbEvKAljAHcXtwEA==) and we should compute the following canonical string: POST,application/json,y1OKcElbEvKAljAHcXtwEA==,/f2pconsole/api/freetoplay/givetokenstousers,Thu, 22 Mar 2018 15:23:15 GMT, from which we can calculate the Base64 encoding of the SHA256 HMAC hash, using the api_secret, which give us oapdEIG5iqI7a/9POrbLUuC4i2PAgQxYBKGWZYWWd6U=. The final Authorization header will then be: APIAuth-HMAC-SHA256 api_key:oapdEIG5iqI7a/9POrbLUuC4i2PAgQxYBKGWZYWWd6U=.

\n","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","toc":[],"owner":"1255977","collectionId":"e28f6e64-c8e0-f2ac-67be-58854e4ca203","publishedId":"6YzuD1s","public":true,"customColor":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"EF5B25"},"publishDate":"2018-04-04T14:55:59.000Z"},"item":[{"name":"GiveTokensToUsers (deprecated)","event":[{"listen":"prerequest","script":{"type":"text/javascript","exec":["var ApiAuth = eval(globals.loadApiAuth);","ApiAuth.computeSignature();",""]}},{"listen":"test","script":{"type":"text/javascript","exec":["tests[\"Status code is 201\"] = responseCode.code === 201;",""]}}],"id":"f6657e34-7955-e59e-e87f-a1eba6744d8c","request":{"method":"POST","header":[{"key":"Authorization","value":"{{api_auth_sha}} {{api_auth_key}}:{{signature}}"},{"key":"Date","value":"{{time}}"},{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"},{"key":"Content-MD5","value":"{{content-MD5}}"}],"body":{"mode":"raw","raw":"[\n {\n \"user_id\" : \"john23\",\n \"plays\" : \"2\"\n },\n {\n \"user_id\" : \"amy27\",\n \"plays\" : \"1\"\n }\n]"},"url":"{{api_url}}{{api_base}}/freetoplay/givetokenstousers","description":"

Behavior:

It gives to the specified users a FreeToPlay token, containing the corresponding number of plays or it will increase the current number of plays in an already valid token if in the same ApiCampaign.

At the moment, the first available ApiCampaign is used.

An ApiCampaign can be created via the FreeToPlay console access provided by Colossus Bets.

Parameters:

An array of hashes containing 2 keys:

user_id - the id of the user in your system (the one that Colossus receives from the user authentication/user info endpoint on your wallet)
plays - the amount of plays(nr of lines) that the user can play for free

\n","urlObject":{"path":["freetoplay","givetokenstousers"],"host":["{{api_url}}{{api_base}}"],"query":[],"variable":[]}},"response":[],"_postman_id":"f6657e34-7955-e59e-e87f-a1eba6744d8c"},{"name":"ClaimTokens","event":[{"listen":"prerequest","script":{"id":"6b4842a9-8ff0-4f49-8ef0-f476319d43bd","exec":["var ApiAuth = eval(globals.loadApiAuth);","ApiAuth.computeSignature();",""],"type":"text/javascript"}},{"listen":"test","script":{"id":"4981b548-1093-4dba-b573-742e4a5bfded","exec":["tests[\"Status code is 201\"] = responseCode.code === 201;",""],"type":"text/javascript"}}],"id":"8e128338-a9a2-4bb2-a0bc-3bc4c4c0d8f9","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"POST","header":[{"key":"Authorization","value":"{{api_auth_sha}} {{api_auth_key}}:{{signature}}"},{"key":"Date","value":"{{time}}"},{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"},{"key":"Content-MD5","value":"{{content-MD5}}"}],"body":{"mode":"raw","raw":"{\n \"campaign_id\": 502,\n \"users\": [\n {\n \"user_id\" : \"nandobermejo\",\n \"plays\" : \"2\"\n }\n ]\n}"},"url":"{{api_url}}/api/freetoplay/claimtokens","description":"

Behavior:

An ApiCampaign can be created via the FreeToPlay console access provided by Colossus Bets.

Parameters:

campaign_id - the id of the created campaign in the console
users - an array of hashes (an empty array is valid as well, no tokens are assigned in that case) containing:
- user_id - the id of the user in your system (the one that Colossus received or will receive from the user authentication/user info endpoint on your wallet)
- plays - the amount of plays(nr of lines) that the user can play for free
\n

Responses

Success responses:

201 created All tokens have been assigned.

Client error responses: (some of them are accompanied by a readable error message)

400 bad request In any of the following cases:
- The body is missing either the campaign id or the list of users, or any of the users in the list is missing either\nthe customer_id or the number of plays.
- The campaign is not active.
- The campaign has reached its limit of assignable tokens.
\n
401 unauthorized APIauth authentication failed or wrong merchant credentials
404 not found The campaign was not found.

Server error responses:

500 internal server error Usually this means the partner configuration is absent, in this case please contact us.

\n","urlObject":{"path":["api","freetoplay","claimtokens"],"host":["{{api_url}}"],"query":[],"variable":[]}},"response":[],"_postman_id":"8e128338-a9a2-4bb2-a0bc-3bc4c4c0d8f9"},{"name":"Badges","event":[{"listen":"prerequest","script":{"type":"text/javascript","exec":["var ApiAuth = eval(globals.loadApiAuth);","ApiAuth.computeSignature();",""]}},{"listen":"test","script":{"type":"text/javascript","exec":["tests[\"Status code is 201\"] = responseCode.code === 201;",""]}}],"id":"45fb9db1-4296-4196-9b51-c672410a48da","request":{"method":"GET","header":[{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"}],"body":{"mode":"raw","raw":"{\n \"campaign_id\": 1,\n \"users\": [\n {\n \"user_id\" : \"john23\",\n \"plays\" : \"2\"\n },\n {\n \"user_id\" : \"amy27\",\n \"plays\" : \"1\"\n },\n {\n \"user_id\" : \"2376890\",\n \"plays\" : \"2\"\n }\n ]\n}"},"url":"{{microsite_api_url}}/api/users/{{id}}/badges/","description":"

Behavior:

It gives the amount of plays (number of lines) that the user can play for free. It can be used to show the number of free plays available for a customer outside of the iframe.

Parameters:

id - the id of the user in your system (the one that Colossus receives from the user authentication/user info endpoint on your wallet)

Responses

Success responses:

200 OK
{freeplays: 3}

Error responses:

404 Not Found
{code: \"COULDN'T FIND USER\"}

\n","urlObject":{"path":["api","users","{{id}}","badges",""],"host":["{{microsite_api_url}}"],"query":[],"variable":[]}},"response":[],"_postman_id":"45fb9db1-4296-4196-9b51-c672410a48da"},{"name":"GetCampaigns","event":[{"listen":"prerequest","script":{"id":"fe287a81-8b0b-4539-8469-aeca4f63d3de","exec":["var ApiAuth = eval(globals.loadApiAuth);","ApiAuth.computeSignature();"],"type":"text/javascript"}},{"listen":"test","script":{"id":"df952590-aad3-4043-bbb7-1b7716384634","exec":["tests[\"Status code is 201\"] = responseCode.code === 201;",""],"type":"text/javascript"}}],"id":"28515d03-2b4b-40f3-8b87-d0ad650928b2","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[{"key":"Authorization","value":"{{api_auth_sha}} {{api_auth_key}}:{{signature}}"},{"key":"Date","value":"{{time}}"},{"key":"Content-Type","value":"application/json"},{"key":"Accept","value":"application/json"},{"key":"Content-MD5","value":"{{content-MD5}}"}],"url":"{{api_url}}/api/freetoplay/getcampaigns","description":"

Behavior:

It gives a list of campaigns. #WIP

\n","urlObject":{"path":["api","freetoplay","getcampaigns"],"host":["{{api_url}}"],"query":[],"variable":[]}},"response":[],"_postman_id":"28515d03-2b4b-40f3-8b87-d0ad650928b2"}]}