Games from Sinatra

Games from Sinatra

Info

Sinatra is Groove's game catalog and asset management platform. This section covers the APIs used to access game information, marketing assets, and player history data.

Overview

The Sinatra platform serves as the central repository for all game-related data within the Groove ecosystem. It provides comprehensive information about available games, their providers, technical specifications, and marketing materials. Casino operators use these APIs to:

  • Retrieve an up-to-date catalog of available games
  • Access marketing materials for promoting games
  • Retrieve detailed game history for player activity
  • View round details for auditing and support purposes

System Architecture

Sinatra functions as a separate service within the Groove platform, requiring its own authentication flow. All requests to Sinatra APIs must include a valid JWT token obtained through the login process.

graph TD A[Casino Operator] -->|1. Login Request| B[Sinatra Authentication] B -->|2. JWT Token| A A -->|3. API Requests with JWT| C[Sinatra Services] C -->|Game Data| D[Game Catalog] C -->|Marketing Assets| E[Asset Repository] C -->|Player History| F[History Database] style A fill:#f5f5f5,stroke:#333,stroke-width:2px style B fill:#ffe6e6,stroke:#333,stroke-width:2px style C fill:#e6f7ff,stroke:#333,stroke-width:2px style D fill:#f0f0f0,stroke:#333,stroke-width:1px style E fill:#f0f0f0,stroke:#333,stroke-width:1px style F fill:#f0f0f0,stroke:#333,stroke-width:1px

Authentication Process

Before accessing any Sinatra APIs, you must authenticate and obtain a JWT token:

sequenceDiagram participant Casino as Casino Operator participant Sinatra as Sinatra Platform Casino->>Sinatra: Login Request (email, password) Sinatra->>Sinatra: Validate Credentials Sinatra->>Casino: JWT Token Response Casino->>Sinatra: API Request with JWT Header Sinatra->>Sinatra: Validate Token Sinatra->>Casino: Requested Data Note over Casino,Sinatra: Token remains valid for limited time

Authentication Prerequisites

  1. Login Credentials: You need valid Sinatra user credentials (email and password) provided by Groove during onboarding
  2. JWT Token: After successful login, the system returns a jwt-auth header containing your authentication token
  3. Request Headers: This jwt-auth token must be included in all subsequent requests to Sinatra APIs

Available Operations

The Sinatra platform provides the following API endpoints:

Operation Description Endpoint
Login User Authenticate and obtain JWT token /{version}/login/
Retrieve Available Game Providers Get list of game providers /vendors/{version}/view/available
Retrieve Available Games Get game catalog /games/{version}/view/detailed
Retrieve Game Marketing Assets Get promotional materials /games/{version}/assets/{game_id}
Retrieve Game History Get player game history /transactions/{version}/games/history
Retrieve Game History via Paginated Response Get paginated history /transactions/{version}/games/history/api
Retrieve Game History Metadata Get metadata for history /transactions/{version}/games/history/metadata
Retrieve Round Details Get specific round information /transactions/{version}/games/round/details/{casino_id}/{game_id}/{round_id}

Typical Integration Flow

A typical integration with the Sinatra platform follows this workflow:

  1. Authentication: Login to obtain JWT token
  2. Game Discovery:
    • Retrieve available game providers
    • Retrieve complete game catalog
  3. Marketing Integration:
    • Retrieve game marketing assets for website display
  4. Player History Access:
    • Retrieve game history for player activity tracking
    • Retrieve round details for dispute resolution

Implementation Best Practices

When integrating with the Sinatra APIs, follow these guidelines:

  1. Token Management:

    • Store the JWT token securely
    • Implement token refresh logic to handle expirations
    • Never expose the token to client-side code

  2. Data Caching:

    • Cache game catalog and provider data to reduce API calls
    • Implement periodic refreshes (e.g., daily) to ensure data accuracy
    • Always fetch fresh history data to ensure accuracy

  3. Error Handling:

    • Implement proper error handling for authentication failures
    • Handle API rate limits gracefully
    • Provide meaningful error messages to operators and support staff

  4. Performance Optimization:

    • Use paginated endpoints for large data sets
    • Implement efficient filtering on the client side
    • Minimize API calls during peak usage periods
Tip

When retrieving game history, use the paginated response endpoint for large datasets to improve performance and reduce memory usage.

Next Steps

Begin your integration with the Login User endpoint to obtain authentication credentials, then explore the game catalog and history endpoints based on your implementation requirements.

Subsections of Games from Sinatra

Log in user

Log in user

Logs a user into the Sinatra service.

Request endpoint: /{version}/login/

Request Method: POST

Parameter Where To Place Data Type Description
version path String required The API version. Only version 1.0 is currently supported. Other version values are accepted but are treated as 1.0.
Example:1.0

Request body:

Parameter Data type Description
email String required Email address of user logging in.
password String required Password of user logging in.

Response Parameters:

Parameter Data type Description
jwt-auth String required Unique session ID. This session ID is available for only 20 minutes.
This header value must be used in subsequent requests, otherwise the request will not be authorized.

Example Response:

{
  "permissions": [
    {
      "id": 1,
      "name": "View games catalog"
    },
    {
      "id": 27,
      "name": "View Game provider list"
    }
  ],
  "user": {
    "id": 5,
    "email": "tst@domain.com",
    "type": "OPERATOR",
    "password": "somehash",
    "avatar": null,
    "status": 1,
    "entityIds": null,
    "organization": {
      "id": -1,
      "name": "TST",
      "status": 1,
      "available_roles": null,
      "available_vendors": null,
      "available_operators": null,
      "type": "OPERATOR"
    },
    "organization_id": -1,
    "role_id": 1,
    "first_name": "Tst",
    "last_name": "Test",
    "last_login": 1603114441000
  },
  "available_operators": [
    9999999
  ],
  "available_vendors": [],
  "login_as": false,
  "original_email": "tst@domain.com"
}

Error Response:

{
  "errMsg": "Username or Password incorrect"
}

Response codes:

Code Status Message
200 success Login user to site
400 Username or Password incorrect Username or Password incorrect
500 internal server error internal server error

Retrieve available games

Retrieve available games

Retrieves data about the games managed by the Sinatra service.

Request endpoint: /games/{version}/view/detailed

Request Method: GET

Request Parameters

Parameter Where To Place Data Type Description
date_from query String optional The start date from which to get game data. The result contains all games that were added or updated after the specified date. If omitted, the default value is 1970-01-01.
Format: YYYY-MM-DD
Example: 2020-10-01
jwt-auth header String required The session ID received from the login request. The session ID is valid for only 20 minutes.
operator_id query Integer optional Filter the games list to return only available games for the specified casino ID.
Example: 1
sub_provider query String optional Filter the games list to return only available games for the specified game provider IDs. The game provider IDs must be separated by commas.
Example:1,2,3
game_identifire query String optional Filter for games with this text within them(id/name), for example, when searching for 888, it will return game id of 81000888, 89918881, 88800001, same goes for name
game_ids query String optional comma separated game ids to fetch, not space between, example: 1111,22222,3333
game_name query String optional game name to fetch, it will search anywhere in the game name for the text entered, for example search text is mega, all of: Mega 1, 1 Mega, Omega 1 are relevant
version path String required The API version. Only version 1.0 is currently supported. Other version values are accepted but are treated as 1.0.
Example:1.0

Example Response:

Success response:

[
  {
    "gameId": "9999999",
    "gameName": "Test Game _for EvoPlay",
    "gameType": "STANDARD",
    "gameCategory": "Slots",
    "platforms": [
      "Desktop",
      "Mobile"
    ],
    "defaultRtp": "96.21",
    "volatility": "MID",
    "supportJackpot": "No",
    "jackpotType": "RTP",
    "supportFrb": "Yes",
    "minBet": [
      {
        "value": "0.2"
      }
    ],
    "maxBet": [
      {
        "value": "100"
      }
    ],
    "maxExposure": [
      {
        "value": "2500"
      }
    ],
    "releaseDate": "2019-05-05",
    "vendorName": "EvoPlay",
    "subVendorName": "EvoPlay",
    "currencies": [
      "AED"
    ],
    "payLines": "88",
    "restrictedCountries": [
      "AL"
    ],
    "languages": [
      "Arabic"
    ],
    "supportedRegulations": [
      "MGA"
    ],
    "defaultImg": "https://s3-eu-west-1.amazonaws.com/marketing-assets/games-dev/new/dd37270ab6f4a87a8e0beded88de0c0c4c799dfb/GamesCatalogimage/image.png"
  },
  {
    "gameId": "8021042",
    "gameName": "pending gak1",
    "gameType": "BRANDED",
    "gameCategory": "Scratch Card",
    "platforms": [
      "Desktop"
    ],
    "defaultRtp": "12",
    "volatility": "Low-Mid",
    "supportJackpot": "YES",
    "jackpotType": "Local",
    "supportFrb": "No",
    "minBet": [
      {
        "value": "11"
      }
    ],
    "maxBet": [
      {
        "value": "123"
      }
    ],
    "maxExposure": [
      {
        "value": "12"
      }
    ],
    "releaseDate": "2019-05-22",
    "subVendorName": "company3",
    "currencies": [
      "AED"
    ],
    "hitFrequency": "12",
    "restrictedCountries": [
      "AF"
    ],
    "languages": [
      "Armenian"
    ],
    "supportedRegulations": [],
    "defaultImg": "https://s3-eu-west-1.amazonaws.com/marketing-assets/games-dev/new/75fcdb55ed1f1ede58aafaab4af493b1ea06df48/GamesCatalogimage/image.png"
  }
]

Error Response:

{
  "errMsg": "unauthorized"
}

Response codes:

Code Status Message
200 success Login user to site
401 unauthorized unauthorized
403 forbidden_operation forbidden_operation
500 internal server error internal server error

Retrieve available game providers

Retrieve available game providers

Retrieves data about the game providers managed by the Sinatra service.

Request endpoint: /vendors/{version}/view/available

Request Method: GET

Request Parameters

Parameter Where To Place Data Type Description
jwt-auth header String required The session ID received from the login request. The session ID is valid for only 20 minutes.
version path String required The API version. Only version 1.0 is currently supported. Other version values are accepted but are treated as 1.0.
Example:1.0

Example Response:

Success response:

[
  {
    "id": 1,
    "name": "providerName1",
    "organization_name": "organizationName1"
  }
]

Error Response:

{
  "errMsg": "unauthorized"
}

Response codes:

Code Status Message
200 success Got available game providers successfully
400 Bad Request Bad Request
401 unauthorized unauthorized
403 forbidden_operation forbidden_operation
500 internal server error internal server error

Retrieve game marketing assets

Retrieve game marketing assets

Retrieves marketing assets for a specific game managed by the Sinatra service.

Request endpoint: /games/{version}/assets/{game_id}

Request Method: GET

Request Parameters

Parameter Where To Place Data Type Description
game_id query String required A game ID, which uniquely identifies the game whose marketing assess are returned.
jwt-auth header String required The session ID received from the login request. The session ID is valid for only 20 minutes.
version path String required The API version. Only version 1.0 is currently supported. Other version values are accepted but are treated as 1.0.
Example:1.0

Response Parameters:

None.

Example Response:

Success response:

{
  "Banners": [
    "https://someuri.gaming.com/image1.jpg"
  ],
  "Characters": [],
  "Symbols (Game Elements)": [
    "https://someuri.gaming.com/image1.jpg"
  ],
  "Games Catalog image": [
    "https://someuri.gaming.com/image1.jpg"
  ],
  "Backgrounds": [
    "https://someuri.gaming.com/image1.jpg"
  ],
  "Thumbnails (Game icons)": [
    "https://someuri.gaming.com/image1.jpg"
  ],
  "Logo": [
    "https://someuri.gaming.com/image1.jpg"
  ]
}

Error Response:

{
  "errMsg": "unauthorized"
}

Response codes:

Code Status Message
200 success Successfully retrieved game marketing assets
400 Bad Request Bad Request
401 unauthorized unauthorized
500 internal server error internal server error

Retrieve game history metadata

Retrieve game history metadata

Retrieves the game history metadata for a game managed by the Sinatra service.

Request endpoint: /transactions/{version}/games/history/metadata

Request Method: GET

Request Parameters

Parameter Where To Place Data Type Description
jwt-auth header String required The session ID received from the login request. The session ID is valid for only 20 minutes.
version path String required The API version. Only version 1.0 is currently supported. Other version values are accepted but are treated as 1.0.
Example:1.0

Example Response:

Success response:

{
  "brands": [
    {
      "organizationId": 0,
      "organizationName": "string",
      "operatorId": 0,
      "operatorName": "string",
      "brandId": 0,
      "brandName": "string"
    }
  ],
  "providers": [
    {
      "providerId": 0,
      "providerName": "string"
    }
  ],
  "timePeriods": [
    "string"
  ],
  "gameTypes": [
    "string"
  ],
  "gameCategories": [
    "string"
  ]
}

Error Response:

{
  "errMsg": "unauthorized"
}

Response codes:

Code Status Message
200 success Got games history metadata successfully
401 unauthorized unauthorized
403 forbidden_operation forbidden_operation
500 internal server error internal server error

Retrieve round details

Retrieve round details

Retrieves the round details for a game managed by the Sinartra service.

Request endpoint: /transactions/{version}/games/round/details/{casino_id}/{game_id}/{round_id}

Request Method: GET

Request Parameters

Parameter Data Type Description
casino_id String required The casino ID of the casino from which the round information is retrieved.
Example:1
game_id String required The game ID of the game for which the round information is retrieved.
Example:811111
jwt-auth String required The session ID received from the loginrequest. The session ID is valid for only 20 minutes.
round_id String required The ID of the round whose data is returned.
Example:1
version String required The API version. Only version 1.0 is currently supported. Other version values are accepted, but are treated as 1.0.
Example:1.0

Response Parameters:

None.

Example Response:

Success response:

{
  "status": "Success",
  "action": "url",
  "url": "https://example.com"
}

Error Response:

{
  "errMsg": "unauthorized"
}

Response codes:

Code Status Message
200 success Got round details
401 unauthorized unauthorized
403 forbidden_operation forbidden_operation
422 Invalid parameters Invalid parameters
500 internal server error internal server error

Retrieve game history via paginated response

Retrieve game history via paginated response

Retrieves data about the games managed by the Sinatra service for the past six months. This method returns a paginated API response.

Info

For performance consideration, rounds_ids should be sent

Note

We have rate limit for this endpoint. If you receive a 429 Too Many Requests response, please slow down your requests.

Request endpoint: /transactions/{version}/games/history/api

Request Method: GET

Request Parameters

Parameter Where To Place Data Type Description
Authorization header String required The client sends HTTP requests with the Authorization header that contains the word Basic followed by a space and a base64-encoded string username:password.
Example: To authorize a user demo with password p@55w0rd, the client would send:
Authorization: Basic ZGVtbzpwQDU1dzByZA==
from query String optional The start date from which to get game data. The result contains all games that were added or updated after the specified date. If this parameter is specified with no value, the default value is the current date.
Note: This parameter must be set if the parameter to is set.
Format: YYYY-MM-DD
Example: 2020-10-01
page_number query Integer optional The page number to return. Must be a number greater than 0.
Note: This parameter specifies the number of transactions per page, not the number of rounds.
Default: 1
page_size query Integer optional The number of transactions per page to return. Must be a number greater than 0.
Default: 200
round_ids query String optional Filter the list to return only data for the specified rounds. The round IDs must be separated by a comma. If empty, all rounds are returned.
Example: 1,2
time_period query String optional The time period for which to retrieve data. This parameter is ignored if parameters from and to are specified.
Valid values:
• today
• yesterday
• last 7 days
• last 30 days
Default: today
to query String optional The end date until which to get game data. The result contains all games that were added or updated before the specified date. If this parameter is specified with no value, the default value is the current date.
Note: This parameter must be set if parameter from is set.
Format: YYYY-MM-DD
Example: 2020-10-01
version path String required The API version. Only version 1.0 is currently supported. Other version values are accepted, but are treated as 1.0.
Example: 1.0

Response Parameters:

None.

Example Response:

Success response:

{
  "page_num": 1,
  "size_per_page": 10,
  "total_count": 393,
  "responses": [
    {
      "round_id": "6228772",
      "brand_id": 2544,
      "brand_name": "dudebet",
      "player_id": "131918",
      "game_id": "130300045",
      "bet": 0.05,
      "win": 0.02,
      "currency": "USD",
      "game_status": "completed",
      "transactions": {
        "good_transactions": [
          {
            "type": "wager",
            "description": "Simple",
            "frb": 0,
            "amount": 0.05,
            "currency": "USD",
            "platform": "desktop",
            "timestamp": "2023-07-25 14:44:13",
            "round_id": "6228772",
            "trans_id": "9079730_int",
            "player_id": "131918",
            "brand_id": 2544,
            "operator_id": 1680,
            "organization_id": 5310,
            "brand_name": "dudebet",
            "operator_name": "Perfect Fusion (Gsoft)",
            "organization_name": "Betinspire",
            "provider_id": 109,
            "provider_name": "Bgaming",
            "casino_session_id": "8cc760a80eb9428c9d75086743d8669e",
            "game_id": "130300045",
            "game_name": "Slotomon Go",
            "game_category": "Slots",
            "game_type": "STANDARD",
            "is_test_account": 0,
            "real_money": 0,
            "bet_amount": 0.05,
            "real_bet_amount": 0,
            "win_amount": 0,
            "real_win_amount": 0
          },
          {
            "type": "result",
            "description": "Simple",
            "frb": 0,
            "amount": 0.02,
            "currency": "USD",
            "platform": "desktop",
            "timestamp": "2023-07-25 14:44:13",
            "round_id": "6228772",
            "trans_id": "9079731_int",
            "player_id": "131918",
            "brand_id": 2544,
            "operator_id": 1680,
            "organization_id": 5310,
            "brand_name": "dudebet",
            "operator_name": "Perfect Fusion (Gsoft)",
            "organization_name": "Betinspire",
            "provider_id": 109,
            "provider_name": "Bgaming",
            "casino_session_id": "8cc760a80eb9428c9d75086743d8669e",
            "game_id": "130300045",
            "game_name": "Slotomon Go",
            "game_category": "Slots",
            "game_type": "STANDARD",
            "is_test_account": 0,
            "real_money": 0,
            "bet_amount": 0,
            "real_bet_amount": 0,
            "win_amount": 0.02,
            "real_win_amount": 0
          }
        ],
        "bad_transactions": []
      }
    },
    {
      "round_id": "400000001671150",
      "brand_id": 2544,
      "brand_name": "dudebet",
      "player_id": "131918",
      "game_id": "135000046",
      "bet": 0.3,
      "win": 0,
      "currency": "USD",
      "game_status": "completed",
      "transactions": {
        "good_transactions": [
          {
            "type": "wager",
            "description": "Simple",
            "frb": 0,
            "amount": 0.3,
            "currency": "USD",
            "platform": "desktop",
            "timestamp": "2023-07-25 14:38:44",
            "round_id": "400000001671150",
            "trans_id": "8096704",
            "player_id": "131918",
            "brand_id": 2544,
            "operator_id": 1680,
            "organization_id": 5310,
            "brand_name": "dudebet",
            "operator_name": "Perfect Fusion (Gsoft)",
            "organization_name": "Betinspire",
            "provider_id": 1167,
            "provider_name": "Rival",
            "casino_session_id": "033756ad27754cddbdb1fa99f3fcfb62",
            "game_id": "135000046",
            "game_name": "Daikoku Blessings",
            "game_category": "Slots",
            "game_type": "STANDARD",
            "is_test_account": 0,
            "real_money": 0.3,
            "bet_amount": 0.3,
            "real_bet_amount": 0.3,
            "win_amount": 0,
            "real_win_amount": 0
          },
          {
            "type": "result",
            "description": "Simple",
            "frb": 0,
            "amount": 0,
            "currency": "USD",
            "platform": "desktop",
            "timestamp": "2023-07-25 14:38:44",
            "round_id": "400000001671150",
            "trans_id": "8096704",
            "player_id": "131918",
            "brand_id": 2544,
            "operator_id": 1680,
            "organization_id": 5310,
            "brand_name": "dudebet",
            "operator_name": "Perfect Fusion (Gsoft)",
            "organization_name": "Betinspire",
            "provider_id": 1167,
            "provider_name": "Rival",
            "casino_session_id": "033756ad27754cddbdb1fa99f3fcfb62",
            "game_id": "135000046",
            "game_name": "Daikoku Blessings",
            "game_category": "Slots",
            "game_type": "STANDARD",
            "is_test_account": 0,
            "real_money": 0,
            "bet_amount": 0,
            "real_bet_amount": 0,
            "win_amount": 0,
            "real_win_amount": 0
          }
        ],
        "bad_transactions": []
      }
    }
  ]
}

Error Response:

{
  "errMsg": "bad request"
}

Response codes:

Code Status Message
200 success Got API games history successfully
400 Bad Request Bad Request
401 Authentication information is missing or invalid unauthorized
403 forbidden operation forbidden
422 Invalid parameters Invalid parameters
429 Too Many Requests slow down
500 internal server error internal server error