Platform accounts

Most integrations should skip this page. If your API key represents one casino, none of this applies: 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 Aggregator.gg covers several operator brands.

Account model

An ordinary operator account represents one casino. A platform account represents several brands. Both can have multiple API keys with their own scopes; credentials are not brands.

A platform account is one contract covering many. Your platform credentials access the shared account, 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.

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

Naming the brand

Create your first brand before following the operator quickstart. On supported endpoints, send sub_operator_ref explicitly so catalog, session and grant operations select the intended brand:

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

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

Operation	Brand selector
GET /v1/games	Query parameter sub_operator_ref
POST /v1/sessions	JSON body sub_operator_ref; stable Idempotency-Key also required
GET /v1/sessions/{id}	Query parameter sub_operator_ref
POST /v1/free-rounds	JSON body sub_operator_ref; stable Idempotency-Key also required
GET /v1/free-rounds and POST /v1/free-rounds/{id}/cancel	Query parameter sub_operator_ref

Do not add the selector to every endpoint indiscriminately. Demo sessions, direct game/stakes lookup, provider registry and GET /v1/transactions do not expose that brand selector in the current machine contract. In particular, the transactions endpoint filters by the authenticated identity; it is not a consolidated platform/brand reconciliation feed. Use supported cabinet evidence and arrange brand-level reconciliation with support before launch.

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). Surrounding whitespace is trimmed and case is folded; other invalid characters are rejected, because a repaired typo would mint a phantom brand and split that brand’s money across two identities.

Step check: list the intended registered brand with its explicit ref. If testing fallback separately, confirm an active default and strict mode off first; otherwise expect E6010 or E6005 when the ref is omitted.

Creating brands

Create the brand explicitly before catalog verification and money-path tests. Brand creation uses the account’s provisioning policy; it does not bypass the brand cap or disabled auto-provisioning.

Explicitly, before any traffic:

POST /v1/sub-operators
Authorization: Bearer $AGGREGATOR_API_KEY
Content-Type: application/json

{ "sub_operator_ref": "brand-01" }

Implicit creation is also supported on eligible calls carrying an unknown ref when auto-provisioning is enabled. New-brand provisioning seeds settings and selected catalog entries from the parent platform. Provider enablement and game selection still have to exist, and partial setup can need recovery. Verify the brand catalog before expecting a launch; neither a populated catalog nor an empty one is guaranteed for every new brand.

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 returns 200 with sub_operator_ref and operator_user_id for a created or existing brand. It is idempotent by ref and does not require the session/grant Idempotency-Key header. An optional display_name changes the label, not the machine ref. If provisioning is disabled, contact support to register the brand; this endpoint uses the same provisioning policy.

Step check: create a brand explicitly, then create it again, and confirm the second call returns 200 with the same identity rather than an error or a duplicate.

The default brand

Your first brand becomes the default. A call that omits sub_operator_ref resolves to it rather than failing, when that default is active and strict mode is off. This fallback can misattribute traffic: send an explicit ref on supported endpoints instead of relying on an unwired code path.

There is no reserved default ref. The default is a real brand, 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, while 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, and 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): omitting the ref never creates the first brand. 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. Calls that use the brand resolver must then name their 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.

Step check: with strict mode on, a call without the ref returns E6005 instead of launching against the default brand.

Billing and callbacks

Every brand’s activity bills the platform’s credit balance. Brands have no independent prepaid credit balance or checkout. Use the offers actually available to the platform in the cabinet; do not infer a special price list from the account type.

The current production wallet is shared at the parent platform. Core resolves a brand’s callback URL and signing secret from its parent. Setting independent brand fields does not establish a supported per-brand wallet override. The deployed API page exposes the callback editor for operator accounts; a platform whose editor is absent needs assisted configuration through support.

Store the returned session_id against your own brand and player context when launching. Use that trusted mapping when a signed callback reaches the shared wallet; do not assume the callback carries sub_operator_ref, or that a player identifier alone establishes the brand. Include the resolved operator/brand context in your deduplication namespace together with organization, provider and transaction identity; the parent organization alone does not distinguish its brands. See Callbacks.

Before rotating a shared URL or secret, coordinate active sessions and outstanding deliveries with support. The current release does not guarantee that every session pins both its callback destination and signer for its entire lifetime.

Step check: create a brand, verify its selected catalog and provider access, confirm the shared wallet configuration, then run a human-approved, budgeted session with its explicit ref and a persisted idempotency key. Verify session-to-brand mapping, callback settlement and reconciliation evidence. Repeat for each brand you intend to launch.

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/503	Brand cap reached, or its count could not be verified. Retry only the transient 503.
E6008	400/403	Unknown ref with provisioning unavailable, or an inactive brand.
E6009	409	The platform account is not fully provisioned.
E6010	409	No sub_operator_ref, and you have no active default brand.

Full list with actions on the Error reference.

The imported OpenAPI file still describes platform refs as universally required on some operations. The current resolver also supports the conditional default above. Explicit refs are the recommended interoperable path.