Skip to content

Operator Utils API

The Operator Utils API provides operators with server-to-server endpoints for managing rewards campaigns, rewards, and player enrollments. This API is designed to be called from the operator's backend systems and is not intended for direct player access.

Base URL

The base URL for the Operator Utils API will be provided by the Gamnify team during onboarding. All endpoints are versioned under /v1/.

Authentication

The Operator Utils API uses the same shared-key hash authentication described in the Authentication section. Every request must include the following headers:

Header Type Required Description
X-AUTH-OPERATOR-ID integer Yes The operator ID assigned by Gamnify.
X-AUTH-REQUEST-HASH string Yes SHA-256 hash computed over operatorSecret + requestPath + requestBody.

The hash is computed by concatenating:

  1. The operator's shared key (PrimarySharedKey or SecondarySharedKey)
  2. The relative request URL (path + query string, trailing slashes trimmed)
  3. The raw request body (empty string for GET requests)

Then applying SHA-256 and converting to a lowercase hex string.

string input = $"{authKey}{requestUrl}{requestBody ?? ""}";
string hash = SHA256(input).ToLowerHex();

For full implementation details and examples, refer to the Authentication documentation.

Hash Bypass (Non-Production Only)

In non-production environments, you can set X-AUTH-REQUEST-HASH-BYPASS: true to skip hash validation. This header is ignored in production.

Response Format

All API responses follow a standard envelope format:

{
  "message": "OK",
  "data": { ... },
  "responseCode": "OK"
}
Field Type Description
message string A human-readable message describing the result. Particularly useful for error diagnostics.
data object or array The response payload. Can be a single object, a list, or empty {} for operations with no return data.
responseCode string A machine-readable response code (e.g. OK, ValidationError, NotFound).

Concepts

Campaigns

A Rewards Campaign is a top-level container that groups rewards under a time-bound promotion. Campaigns have a start time, end time, and an optional operator reference for correlation with external systems.

Rewards

A Reward defines what enrolled players will receive. Rewards belong to a campaign and are linked to one or more products (games). Currently the supported reward type is FreeBets.

Enrollments

A Reward Enrollment links a specific player to a reward. Once enrolled, the player can consume the reward within the configured time window and on the specified products.

Hierarchy

flowchart TD
    C[Campaign] --> R1[Reward A]
    C --> R2[Reward B]
    R1 --> E1[Enrollment - Player 1]
    R1 --> E2[Enrollment - Player 2]
    R2 --> E3[Enrollment - Player 3]

Status Lifecycles

Campaign Status

Status Description
Scheduled Campaign created but start time has not been reached yet.
Active Campaign is live; rewards within it can be consumed.
Ended Campaign end time has passed.
Cancelled Campaign was manually cancelled by an operator.

Reward Status

Status Description
Scheduled Reward created but start time has not been reached yet.
Active Reward is live and can be consumed by enrolled players.
Ended Reward end time has passed.
Cancelled Reward was manually cancelled by an operator.

Enrollment Status

Status Description
New Player is enrolled but the reward is not yet active.
Active Reward is active and the player can consume it.
Claimed All bets in the reward have been consumed by the player.
Cancelled Enrollment was cancelled by the operator.
Expired Reward end time passed before the player fully consumed it.

Reward Types

The API uses a polymorphic model for rewards. The rewardType field in request and response payloads acts as a discriminator to determine the concrete type.

Reward Type Discriminator Value Description
Free Bets FreeBets Awards the player a number of free bets with a specified value and currency on selected products.

Compression

All endpoints support response compression. To enable it, include:

Accept-Encoding: gzip

Next Steps