> ## Documentation Index
> Fetch the complete documentation index at: https://developers.teambuilder.ge/llms.txt
> Use this file to discover all available pages before exploring further.

# Sandbox and testing

> Build against realistic sample data with a tb_test_ key, then switch to live by changing one secret.

Every customer gets a private **sandbox company**. A `tb_test_` key reads and writes the sandbox instead of your real company, through the same endpoints, scopes, limits and response shapes. Going live means swapping the key, nothing else.

```bash theme={null}
curl https://api.teambuilder.ge/v1/ping -H "Authorization: Bearer $TEAMBUILDER_TEST_KEY"
```

```json Response theme={null}
{
  "company_id": "0b6c1e2f-4a8d-4f3e-9b71-6d2e8c5a1f04",
  "key_prefix": "tb_test_",
  "scopes": ["employees:read", "leaderboard:read", "departments:read", "shop:read"],
  "mode": "test"
}
```

## What the sandbox contains

The sandbox is created and seeded when your first test key is issued. It is shaped so every endpoint has something meaningful to return:

| Data | Seeded with |
| - | - |
| Departments | Engineering (with a Frontend sub-department), Sales, Marketing, and People & Culture, each with an `external_id` such as `SBX-DEP-ENG`. |
| Employees | Eleven active employees spread across those departments (one has no department), plus one deactivated employee who never appears in responses. External ids look like `SBX-E001`. |
| XP | Earned at different times over the past year and more, so `this_month`, `last_3_months`, `last_year` and `all_time` [leaderboards](/guides/leaderboards) rank people differently. |
| Coins and badges | Balances and badges per employee, for [profile widgets](/guides/employee-widgets). |
| Shop | Four items with sandbox prices and limited stock, for the [shop catalogue](/guides/shop-catalogue). |

Sandbox employees have non-deliverable addresses on a `.invalid` domain, so nobody can sign in as them and no email can ever reach them. The sandbox is excluded from TeamBuilder's analytics and does not appear in your company's TeamBuilder portal.

## Testing roster sync

Test keys with the `employees:write` scope sync into the sandbox. Use them to rehearse your real export before the first live run:

* Emails you send are stored as non-deliverable stand-ins, so real addresses are never kept in the sandbox and nobody is contacted. Because of this, look up synced sandbox employees by `external_id`, not `email`, and expect `email` fields in sandbox responses (including `deactivation_candidates`) to be stand-ins. Names, job titles, HR ids and department names are stored as you send them.
* Your SSO domain restriction does not apply.
* The sandbox holds at most **500** employees; rows that would add more fail with `sandbox_limit_reached`. Trim large exports for test runs.
* Every other rule (matching, departments, deactivation guards, idempotency, rate limits) behaves exactly as in live.

Sandbox data persists between runs and is not reset automatically. If you need a fresh sandbox, [ask us](mailto:contact@teambuilder.ge).

## The API playground

The **Try it** panel on each [API reference](/api-reference/introduction) page sends real requests.

<Warning>
  Playground requests are relayed through the servers of Mintlify, the platform that hosts this documentation, so a key you paste there leaves your machine. **Use only `tb_test_` keys in the playground.** If a live key was ever pasted there, rotate it.
</Warning>

## Moving to live

<Steps>
  <Step title="Get your live key">
    Ask [contact@teambuilder.ge](mailto:contact@teambuilder.ge) for a `tb_live_` key with the same scopes.
  </Step>

  <Step title="Swap the secret">
    Replace the test key in your production secret manager. Keep the test key in development and staging.
  </Step>

  <Step title="Assert the mode">
    On start-up, call `GET /v1/ping` and fail fast if `mode` is not what that environment expects.
  </Step>

  <Step title="Re-resolve ids">
    Sandbox `employee_id` and department `id` values do not exist in your live company. Clear any cached ids and resolve them again with live data.
  </Step>
</Steps>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.