Connecting your operator API

#How it works

The platform defines a fixed set of operations for iGaming support. You map them to endpoints of your own API; each operation belongs to a capability, and capabilities are switched on per integration. Amounts always travel in minor units (e.g. cents) with an ISO 4217 currency.

bonus.grant is the only operation that moves money or changes state. A payment link does not move money, so it counts as a read; its URL is never given to the AI model and is posted to the chat by the platform as a card.

#Setup steps

In the admin console, create a New integration (name and brand) on the Integrations page and follow the wizard. Changes require integrations:write.

1. API document

   Upload an OpenAPI 3.x (JSON or YAML), Swagger 2.0 or Postman Collection v2.1 file of up to 5 MB. External $refs are not supported; the document must be a single file. It is parsed in a separate, isolated service.

2. Mapping

   Suggest with AI produces a draft mapping with a confidence score, notes, unmapped operations and suggested hosts. Review, edit and save the draft. For each operation you define the method, path template, inputs, success status codes, response field paths (e.g. $.data.balance), transforms (e.g. decimal amount to minor units, value mapping, date format) and error rules.

3. Hosts & credentials

   Enter the hosts the API may be called on as exact host[:port] values (no wildcards, up to 10). Hosts found in the document or the suggestion are listed but never approved automatically. Then choose the authentication type and enter the values (see below).

4. Conformance

   Tests run against your sandbox. You provide an existing player id and a different, unknown one; for the bonus test, optionally a campaign, amount and currency. The tests check the schema of each read, that sending the same bonus request twice grants a single bonus, reconciliation after a timeout, error mapping and latency.

5. Publish & capabilities

   Publishing needs a passed conformance run that proves player.read. Published versions are immutable; changes go into a new draft and a new version. Capabilities are switched on separately and only proven ones can be enabled; bonus.grant also needs player.read and restrictions.read. Finally activate the integration (credentials must be set).

The Try it runner calls one mapped read operation on the draft or the active version and shows the result; the Versions tab shows a diff between definitions.

#Credentials

Credentials are stored encrypted with the connector service’s public key (RSA-OAEP-256 + A256GCM). Neither the Core API nor the admin console can decrypt them; the console only shows which fields are stored. To change them, enter all values again.

#Network and safety rules

• Only allowed hosts are called, and only over https.
• Every IP address the host resolves to must be public; private, loopback, link-local/metadata and similar ranges are blocked. The connection is pinned to the checked IP.
• Credentials in URLs are rejected, redirects are not followed and responses are capped at 2 MB.
• The default timeout is 8 seconds, adjustable per operation between 0.5 and 30 seconds. Reads are attempted at most twice; bonus.grant is never retried blindly.
• After 5 consecutive failures a circuit breaker pauses new calls for 30 seconds.

#Player binding

Reads only run for players verified with a signed identity token. The player id in the call is always filled in with the verified player linked to the conversation. Results are cached briefly (30 seconds) and given to the assistant as verified facts; the assistant may only state amounts that appear in them. Sensitive data such as card numbers, Turkish national ID numbers and IBANs is masked before it reaches the model.

#Bonuses, policy and approval

Bonus grants are governed by the Action policy in the admin console: whether bonuses are enabled, player confirmation in the widget, a KYC requirement, human approval above an amount, a maximum per bonus, a tenant total per day, a per-player daily limit and a separate daily limit for AI-initiated requests, and confirmation and approval timeouts. Campaigns are defined on the Bonus campaigns page.

Every bonus request goes through these checks in order; the first denial stops it:

1. is the player verified with a signed identity;
2. is the capability enabled;
3. restrictions (e.g. self-exclusion; denied if they cannot be checked);
4. KYC (if the policy requires it);
5. is the campaign active and does it match the brand; campaign rules;
6. the operator’s eligibility answer (bonus.eligibility);
7. amount and frequency limits; duplicate check.

The player then confirms the offer in the widget (if the policy requires it). Above the human-approval threshold the request waits for someone with actions:approve; nobody can approve their own request, and the policy is evaluated again at approval time. The grant is sent with a one-time idempotency key. If the outcome is unknown (timeout, lost connection), the platform reconciles with bonus.lookup. The player is told only after a verified success.

#Monitoring

The Diagnostics tab under Operations & incidents shows the integration call log (filterable by outcome and operation); incidents are opened when error-rate and latency thresholds are exceeded. Provider call logs are deleted after 30 days.