Skip to main content

​
Overview

Gameball’s Secure Integration Mode is built around two core ideas:
  1. All integration APIs must be called from your backend using your SecretKey.
  2. All widget/mobile access must be tied to a short-lived, per-customer session token.
This page focuses on the first part: Integrations v4.1 and the Minimum Secure Version control.

​
1. Integrations v4.1 – What Changed

Previously, some integration endpoints could be called using only the public APIKey. In v4.1 we have standardized security across all integration APIs:
  • All endpoints under: 
    https://api.gameball.co/api/v4.1/integrations/...
    now require:
    • APIKey: <your-public-api-key>
    • SecretKey: <your-private-secret-key>
  • Requests without SecretKey are rejected.
  • Integrations traffic is expected to be server-to-server only:
    • No calls from browsers.
    • No calls from mobile apps directly.
    • No exposure of the SecretKey in any public client.
This effectively makes the previous “High Security Mode” behavior mandatory for v4.1 integrations.

​
2. Security Model

In Secure Integration Mode:

​
Integration APIs (v4.1)

  • Only callable from your backend.
  • Authenticated by both APIKey and SecretKey.
  • Used for: customer creation/updates, points transactions, events, etc.

​
Customer access to Gameball (widgets / SDKs)

  • Tied to a per-customer JWE session token (see separate page).
  • The widget still uses playerUniqueId (your customer identifier).
  • Gameball validates that:
    • The token is signed and encrypted with your SecretKey.
    • The customerId in the token matches the identity you’re passing.
Together, this gives you:
  • A sealed integration surface (only from your servers).
  • Per-user authorization for anything the widget shows or does.

​
3. Migrating Existing Integrations to v4.1

​
3.1 Inventory your current calls

Find all usages of: 
https://api.gameball.co/api/v4.0/...
and list:
  • Which endpoints you call.
  • Which ones do not include the SecretKey.
  • Anything that is currently called from browser JS / mobile is already a security issue and must be moved to your backend.

​
3.2 Update the base URL

For backend integrations: Change v4.0 to v4.1: 
https://api.gameball.co/api/v4.1/...

​
3.3 Enforce SecretKey in every call

For each v4.1 call, make sure you set:
  • APIKey header (public key)
  • SecretKey header (private key, never exposed to clients)
If you centralize your HTTP client for Gameball, this is the right place to enforce both headers.

​
3.4 Validate server-only usage

Confirm:
  • No Gameball HTTP call is made from browser JS.
  • No Gameball HTTP call is made directly from mobile apps.
  • Everything must go: Client → your backend → Gameball v4.1 integrations.

​
3.5 Stage, test, and deploy

  1. Deploy to a staging / test environment.
  2. Run all scenarios:
    • Customer creation updates.
    • Events and transactions.
    • Any custom flows you have.
  3. Once stable, roll out to production.

​
4. Minimum Secure Version

Once you are fully on v4.1 and using per-customer session tokens for widgets, you can enforce a minimum allowed version from the Gameball Dashboard.

​
4.1 What Minimum Version does

When you set: 
Minimum allowed version = v4.1
Gameball will: Reject:
  • Any integrations call using older versions (v3.0, v4.0, etc.).
  • Any widget / SDK access that doesn’t meet secure requirements (e.g. missing session token where required).
Accept only:
  • Integrations called through /api/v4.1/integrations/... with APIKey + SecretKey.
  • Widgets / SDKs that use playerUniqueId and a valid per-customer session token.
Effectively, anything that isn’t using the new security pattern simply stops working.
1

Integrations migrated

All backend integrations call v4.1 with APIKey and SecretKey.
2

Widgets / SDKs migrated

Your web and mobile apps are using session tokens (see Session Tokens doc).
3

Monitoring period

Keep minimum version relaxed. Monitor logs/dashboard for any remaining older-version traffic.
4

Enforce minimum version

Set minimum version to v4.1. Keep an eye on errors in the first days to catch any forgotten integrations.

​
5. Typical Backend Flow with v4.1

This is about when your backend talks to Gameball in a typical application:

Customer Registration

Customer created / registered in your system → Backend calls v4.1 integrations to create a matching Gameball customer.

Profile Updates

Customer profile updated (email/mobile/name/etc.) → Backend calls v4.1 integrations to sync attributes.

Business Actions

Customer performs a business action → Backend logs the event / transaction to v4.1 integrations.

Login Flow

Customer logs in to your app → Backend generates a Gameball session token using their customerId and your SecretKey.

Widget Initialization

Widget / SDK initializes → Frontend / mobile uses playerUniqueId and the session token.

Version Enforcement

Minimum version is enforced → Any old pattern (direct browser calls with APIKey only, old endpoints, etc.) simply fails instead of exposing you.
That’s the lifecycle you want to push all your teams towards.

​
Base URL

The API base URL for v4.1 integrations: 
https://api.gameball.co/api/v4.1/integrations/...

​
Authentication

All v4.1 integration endpoints require both APIKey and SecretKey headers. Requests without SecretKey are rejected.

​
Example: Authentication with API Key and Secret Key

curl --request POST \
  --url 'https://api.gameball.co/api/v4.1/integrations/event' \
  --header 'APIKey: ue7eh32eiwlsncoko08u8b' \
  --header 'SecretKey: kz7eh32eiwldlowbo08u5p'
For detailed authentication instructions, refer to the Authentication section.

Session Tokens & JWE

Learn how to generate and use per-customer session tokens for widgets and mobile SDKs

API v4.0 Documentation

Reference documentation for the previous API version

Authentication Guide

Detailed authentication instructions and best practices

Migration Guide

Step-by-step migration from v4.0 to v4.1