Custom domain (CNAME)

One record, per environment

Point the host at our edge with a CNAME. Do not resolve it to an origin address with an A record: a request that reaches an origin without passing the edge has skipped tenant routing, the certificate check and the embedding policy in one step, and nothing downstream can reconstruct them.

; sandbox
play.sandbox.your-brand.com.   CNAME   <edge hostname — issued by the operator>.

; production
play.your-brand.com.           CNAME   <edge hostname — issued by the operator>.

The edge hostname is issued to you, not derived. It differs per environment and per deployment, so there is no value to guess or copy from another integration — take it from your onboarding contact and use it verbatim. Registration records the hostname you were told to expect, and the review below compares your live record against it.

Sandbox and production domains are registered separately and reviewed separately. Nothing about an enabled sandbox domain carries over. See Environments & endpoints for what else is separate between the two.

Registration and review

Registration is yours; activation is ours. You submit the host yourself from the integration page of your merchant console — there is no operator endpoint that creates a registration, so nothing about this step waits on us — and the operator then reviews and activates it. A domain moves through three states, and the path between them is deliberately narrow.

1. 1. You submit the host you want to serve from, in your console. It is normalised to lowercase without a port, and it must be a real multi-label name. The registry is globally unique across live registrations: a name held by any registration that has not been withdrawn — under any merchant, pending, enabled or disabled alike — is refused as a conflict rather than re-pointed. You may hold one pending registration at a time; a second submission is refused until the first is activated or withdrawn, and withdrawing is the way out of a typo rather than waiting for a review that will never pass.
2. 2. The row is created in pending. Nothing about it is live: the exchange on that host answers 401 and anonymous browsing answers 404, exactly as for a host that was never submitted.
3. 3. Once your CNAME resolves and the certificate covers the host, the operator runs activation. It checks the conditions below in order and refuses on the first one that does not hold.
4. 4. Inside the same transaction as the status flip, a canary exercises the domain for real. If it does not pass, the whole activation is rolled back and the domain stays pending.
5. 5. Only then is the domain enabled, and the credential, embedding and realtime bindings at the bottom of this page start to apply to it.

What activation checks, in order:

• • The row is pending. A disabled domain is refused here — that is the rule that makes withdrawal one-way.
• • Your merchant is enabled. Fail-closed: if the merchant record cannot be read at all, activation is refused rather than assumed.
• • Ownership is proven, if this name was ever someone else's. A name whose earlier registration belonged to a different merchant needs a fresh DNS TXT proof before it can be activated — see below. First registrations, and re-registrations by the same merchant, do not go through this.
• • Certificate, Host/SNI consistency and frame-ancestors are confirmed. These three are signed off by a human against live output, because the platform cannot verify its own edge from the inside. They are what the operator is testing when they ask you to leave the record in place and wait.
• • Your CNAME is probed once and compared against the expected edge hostname. This one is advisory: a probe that times out or disagrees is recorded in the audit trail rather than blocking, because DNS propagation and split-horizon resolvers make it an unreliable gate. The canary is the gate.
• • The canary passes. Blocking, and the only check that exercises the real path end to end.

The canary — why enabled is never a paper state

Activation performs, against your host, exactly one sa1 credential exchange and exactly one launch-token exchange. Both must succeed. Either leg failing rolls the transaction back — the status flip included — so the domain returns to pending with the failing leg and its reason written to the audit trail. There is no state in which a domain is marked enabled but has never served a successful entry.

The two legs are not redundant. They are the two entry mechanisms — a locally signed credential and a console-minted token — and they fail for different reasons: the sa1 leg covers signature verification, the clock window, the Host binding, merchant status and nonce burn in one shot, while the launch-token leg covers minting and redemption. A domain that passes one and not the other is a real and specific finding, which is why the result records them separately.

Two side effects are worth knowing before you see them. The probe runs under a reserved player id, pp-domain-canary, so that id appears under your merchant after a domain is activated; it never holds funds and never places an order. And the session the canary creates is revoked immediately after the activation commits, so it does not sit in your session list and does not consume the one-session-per-player slot of any real player.

One enabled domain, and what happens with none

A merchant has exactly one enabled domain per environment, and that is the host POST /b2b/v1/auth/launch-token builds game_url on. There is no primary flag to set and no second domain to choose between: enabling a replacement retires the previous one in the same transaction, so there is never a window with two.

With none enabled, the launch call refuses — a stable merchant_domain_not_ready, with no game_url in the response. It does not fall back to a platform-hosted origin; there is no longer one to fall back to. If you are working from an older description that promised a working-but-unbranded link in this situation, that behaviour is gone, and so is the failure mode it caused: a launch URL quietly pointing somewhere unexpected after a domain change.

The honest consequence of a single entry is that changing domains is a cutover with a visible seam, not a zero-downtime migration. The old host is refused the instant the new one is enabled, and every iframe already open on it needs a fresh launch to come back. Mitigate it the way you would any DNS cutover — lower the TTL in advance, complete the certificate, Host/SNI and ancestor checks on the new host before the switch, pick a window, and have the parent page rebuild its iframes afterwards. It also means availability has to be solved on that one host: certificate renewal you watch, edge failover, and continuous DNS and TLS probing. A second tenant entry is not the answer, and is not offered.

Disabling is one-way

A domain can be disabled at any time and stops serving immediately. It cannot be switched back on. Restoring it means resubmitting it to pending and passing the entire review again, canary included. That is deliberate — a domain is disabled because something about it stopped being true (the certificate, the DNS record, the edge association, the relationship), and none of those come back just because the row is flipped. What a disabled registration keeps is the history: it stays on file under your merchant, it still holds the name, and it is the object you resubmit. Only the operator can remove one — see the next section for why that boundary sits where it does.

Plan the DNS side with it. A domain that is disabled while its CNAME still points at our edge is a dangling record; retire the record at the same time, and do not create the record before the domain has been registered, so that the name is never resolving to an edge that has nothing on file for it.

Withdrawing a registration, and reusing a name

A name is held by live registrations only. Withdrawing one releases it: the row becomes a tombstone that keeps the audit history but leaves the uniqueness key, so the same host can be registered again afterwards — by you, or by somebody else. A re-registration is always a new registration with a new id; a withdrawn one is never revived, and no setting on it survives.

Who can withdraw what follows the same principle as the rest of the lifecycle — you can undo what was never reviewed, and the operator handles anything that has been live.

• • You, from your console: your own pending registration, and only if it has never been enabled. That last part is a separate check rather than a reading of the current status, because a disabled registration can legitimately be resubmitted back to pending — without it, two individually legal steps would add up to erasing a domain you had actually run on.
• • The operator: any pending or disabled registration. An enabled one is refused outright — disable it first, which keeps “still serving” and “removed” from ever being the same moment.

Console writes on domains — submit, resubmit and withdraw — share one abuse budget: ten per ten minutes and thirty per UTC day, per merchant, counted on attempts rather than on successes, and answering 429 past either. A normal integration spends three or four of these in its life; you will only meet the limit by scripting a submit/withdraw loop, which is what the budget is there to stop.

What the domain is bound to, once enabled

Two things same-origin changes for you

Serving the player surface from your own host is what makes the browser's calls same-origin. That buys one thing and costs one thing, and both are worth reading before you pick the host name.

When it does not work

Domain faults and credential faults look identical from inside the player's browser — both are usually a bare failure with no reason. The status code separates them, so read that first.

Where this sits in the integration

The domain gates everything the player touches and nothing your servers touch. The B2B surface you sign against does not use it and the money path does not either — those keep working on a merchant whose domain is still pending, which is exactly why an integration can look healthy from your backend while no player can be launched. Once the domain is enabled, return to the Quick Start at step 3 and mint a launch token; if you sign sa1 credentials yourself, set h to this host.