Platform accounts

Most integrations should skip this page

If your API key represents one casino, none of this applies to you. There is no sub_operator_ref to send, no brand to name, nothing to configure. Sending the field from an ordinary operator key is an error (E6006), not an optimisation.

This page is only for platform partners — a casino-management provider whose single contract with The Aggregator covers several operator brands.

What a platform account is

A normal operator account is one casino: one key, one catalog, one credit balance, one line in your invoice.

A platform account is one contract covering many. You hold a single API key, and each casino you serve is a brand beneath it — a sub-operator, which is where the parameter name comes from. Every brand gets:

• its own catalog — providers and titles are enabled per brand, so two brands under your key can legitimately show different games;
• its own attribution — sessions, transactions and analytics are recorded against the brand, not against you;
• your bill — every brand’s spins draw down the platform’s credit balance. Brands do not hold balances, do not log in, and are not parties to your agreement with us.

That last point is the whole model: you are the customer, the brands are how your traffic is broken down.

Naming the brand: sub_operator_ref

Every operator-scoped call takes an optional sub_operator_ref naming which brand it acts as:

POST /v1/sessions
Authorization: Bearer sk_live_...
Idempotency-Key: 6f1c...
Content-Type: application/json

{
  "game_id": "0e04ed04-991e-4407-86fb-a65f428cb7af",
  "player_id": "player-42",
  "balance": 100.00,
  "currency": "EUR",
  "country": "MT",
  "sub_operator_ref": "brand-01"
}

The same ref goes on GET /v1/games, on the session read-back, and on all three free-rounds routes. A brand’s spins are only counted as that brand’s when the call carried its ref.

Format: 1–32 characters of [A-Za-z0-9_-], starting and ending alphanumeric. Matched case-insensitively, so Brand-01 and brand-01 are one brand rather than two. A ref that does not match is a 400 (E6004) — refs are validated and never silently repaired, because a repaired typo would mint a phantom brand and split that brand’s money across two identities.

Creating brands

Two ways, and they produce identical results:

Explicitly, before any traffic:

POST /v1/sub-operators
Authorization: Bearer sk_live_...
Content-Type: application/json

{ "sub_operator_ref": "brand-01" }

Implicitly, on first use: a launch or a GET /v1/games carrying a ref we have not seen creates the brand on the spot, with the same games and providers your platform already has available. Its catalog is usable immediately — no onboarding step, no support ticket.

Prefer the explicit call when you can. It keeps brand creation off the money path, it works under strict mode, and it makes a typo distinguishable from a genuine new brand — auto-provision cannot tell them apart.

POST /v1/sub-operators is idempotent: an existing ref returns the same identity with 200. Re-running your brand list on every deploy is a normal thing to do.

The default brand

Your first brand becomes the default. A call that omits sub_operator_ref resolves to it rather than failing, so a code path that has not been wired yet still launches — its spins are simply attributed to the default brand instead of the intended one.

There is no reserved default ref. The default is a real brand, and it is whichever one you created first.

Omit the field — never send it empty

An absent sub_operator_ref resolves to your default brand. An empty one ("" or whitespace) is a 400 (E6004).

The two are different signals. A field you never sent cannot have been meant to name a brand. A field you sent blank means your integration has the parameter and the value behind it came out empty — that request believes it selected a brand. Answering it with your default one would attribute the spins, and the bill, to a different brand while returning 201 as if nothing were wrong.

So: build the field conditionally. Include it when you have a ref, leave it out entirely when you do not.

If your platform has no brands at all, a call that omits the ref is a 409 (E6010) — a brand is never created for the first time on the money path. Create one with POST /v1/sub-operators.

Strict mode

If you would rather a missing parameter fail loudly than land on a default, ask support to enable require_sub_operator_ref on your account. Every operator-scoped call must then name its brand, and omitting it is a 400 (E6005).

Worth enabling once you run enough brands that “attributed to the default” would be a silent accounting problem rather than an obvious one.

Billing and callbacks

Every brand’s activity bills the platform’s credit balance — one balance, one top-up flow, one invoice, however many brands you run. Brands do not hold credit of their own.

Wallet callbacks are configured per brand, in the same place an ordinary operator configures theirs. A brand created by auto-provision inherits your platform’s settings, so check its callback_url before you expect settlement to complete: a brand with no wallet URL launches fine and then cannot settle.

Error codes

Code	HTTP	What it means
E6004	400	The ref is malformed, or was sent empty.
E6005	400	Omitted, and your account runs require_sub_operator_ref.
E6006	400/403	Sent from a key that is not a platform key.
E6007	400	Your platform is at its brand cap.
E6008	400	Unseen ref, and auto-provisioning is disabled for you.
E6009	409	The platform account is not fully provisioned.
E6010	409	No sub_operator_ref, and you have no default brand yet.

Full list on the Error codes page.