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 mismatched | What the host should do | What you change afterwards |
|---|---|---|
| Sandbox key on the production host | Reject 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 harness | Rotate 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 ticket | The 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 brand | Revoking 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
- 01
Reject the wrong environment
A sandbox key on the production host is an error, not a convenience.
- 02
Rotate
Keep secrets out of the repo and support an overlap window when you rotate.
- 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
| Secret | Where it belongs | What a leak or a mismatch costs |
|---|---|---|
| Launch credential, test | Secret store, test scope only | A production launch attempted with it fails at the host, which is the point |
| Launch credential, production | Secret store, one entry per brand or environment | Every session under that key is open until it is rotated |
| Wallet callback encryption key | The AES key that decrypts the wallet callback | An unverified caller can attempt debits and credits in your name |
| Event webhook secret | Secret store, named per environment | A replay from staging reads as live traffic |
| Dashboard logins | Identity provider, named people | A 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.