Turnkeyxgaming

Guide · Integration

Sandbox keys must not open production

The usual serious incident in a new integration is not a bad debit. It is a sandbox key deployed to production, or a production key left in a test harness that several people can read.

7 min readUpdated By the Turnkeyxgaming team

Different secrets, different hosts

Issue a separate key pair per environment and reject the wrong one at the edge. IP allow-lists help and are not enough, because build servers move. Rotation should be possible without a code change: the secret lives in a secret store, and the previous secret can be accepted for a short overlap so you are not forced to cut every connection in one second.

Logs are where keys leak next. Do not log decrypted payloads or any input that includes the key, and do not paste a production launch URL into a ticket. A launch URL is a bearer for that session. Treat it like a password in front of support tools that retain text.

Put each secret in a store the deploy reads, not in the repo and not in a shared note. Rotation swaps that entry and keeps a short overlap where the previous key still decrypts, so you do not have to drop every connection in one second. After the overlap, the old key fails. A sandbox key on the production host fails immediately. Build servers move, so an IP allow-list is a help and not the control.

Where a key usually ends up in the wrong place

The serious early incident is a secret in the wrong environment, not a malformed debit. Reject the mismatch at the edge and keep the secret out of text that gets retained.

What leaked or mismatchedWhat the host should doWhat you change afterwards
Sandbox key on the production hostReject it. Do not treat it as a convenience for a developer who is in a hurry.Nothing in production was opened. Fix the deploy config.
Production secret in a repo or a test harnessRotate as soon as you notice. Assume the old secret is copied.Use the overlap so live traffic moves, then refuse the old secret.
Launch URL pasted into a ticketThe token is a bearer until it expires. Expire it.Stop putting session URLs in tools that retain text. A key in a log is the same class of leak.
One key shared by every brandRevoking it is a group-wide outage.Prefer a key per brand or per environment. The wallet still checks the brand id on the call.

Key handling

  1. 01

    Reject the wrong environment

    A sandbox key on the production host is an error, not a convenience.

  2. 02

    Rotate

    Keep secrets out of the repo and support an overlap window when you rotate.

  3. 03

    Scrub tickets

    Do not leave launch URLs or keys in shared tickets.

An allow-list is not a second secret

A production key that still verifies because the caller sat inside an allow-list is still a production key. Reject the wrong key at the host. Keep the secret in a store outside the repo.

Four secrets, not two

The phrase the API key hides a small estate. A brand usually ends up with a launch credential per environment, a wallet callback encryption key per environment, a secret for any event webhook, and dashboard logins for the people who administer the catalogue. Rotating one of those four and calling the work done is how the other three reach their second birthday.

Walk a staging deploy on a Tuesday. The pipeline reads a variable group named after the service rather than the environment, so staging and production differ by a base URL in a config file. A callback replay from a test run now posts a real debit against a real balance, because the payload decrypted with the production key. The amount is small, which is why a monthly reconciliation finds it rather than an alert.

The cheap control is host-level rejection of the other environment, and the cheap discipline is a named inventory. Write down each secret, where it lives, who can read it, who rotates it and what stops working when it changes. That last column is the one people skip, and it is the one that turns a rotation into a call at eleven at night.

The secret inventory, with its blast radius written down

SecretWhere it belongsWhat a leak or a mismatch costs
Launch credential, testSecret store, test scope onlyA production launch attempted with it fails at the host, which is the point
Launch credential, productionSecret store, one entry per brand or environmentEvery session under that key is open until it is rotated
Wallet callback encryption keyThe AES key that decrypts the wallet callbackAn unverified caller can attempt debits and credits in your name
Event webhook secretSecret store, named per environmentA replay from staging reads as live traffic
Dashboard loginsIdentity provider, named peopleA shared login cannot be revoked for one leaver

FAQ

Questions operators ask

Can one key serve all of our brands?

Prefer a key per brand or per environment so you can revoke one brand without a group-wide outage. The wallet still checks the brand id on each call.

Can every brand in the group share one production key if the brand id is on the call?

The brand id still has to be checked, and a shared key means you cannot revoke one brand without rotating the group. Prefer a key per brand or per environment so a leak has a boundary.

How do we rotate without dropping every live session in the same second?

Accept the previous secret for a short overlap while deploys pick up the new one, then reject the old secret. Do not leave both secrets valid over a weekend.

Staging and production differ only by base URL. Is that acceptable?

It is the configuration that makes a wrong-environment call both possible and undetectable. Separate keys, host rejection of the other environment's credentials, and a callback host that cannot reach production data turn a bad deploy into a failed request. None of those three is expensive once it exists.

Who should be able to read the production key?

The smallest set that can still deploy and support the integration, reading through the secret store rather than a shared document. Support needs to open a launch occasionally; it does not need the key that decrypts one. If a person cannot be removed from the reader list on their last day, the list is too wide.

Keep reading

Related pages

  • IntegrationIntegrationSandbox keys, AES-encrypted wallet callbacks and the four wallet endpoints, then a 24–72 hour go-live once decryption and retries pass.Read
  • DocumentationAPI docsAuthentication, the game list, demo and real launch, AES-encrypted wallet callbacks and error handling, with test keys to start.Read
  • Guide · TestingSandbox versus invoicesHow to separate sandbox players, test currencies and staff accounts from the GGR file that becomes an invoice, with examples.Read
  • Guide · IntegrationSeveral brandsRun several brands on one integration without sharing catalogues, limits or GGR. The contract is shared; the players are not.Read

Get a written quote and sandbox access

Tell us your licence, target markets and products. You get the GGR rate in writing, the studio list for your markets and sandbox credentials.

Telegram @turnkeyxhub WhatsApp Email Contact form