# Sandbox

The sandbox answers every endpoint of the public API with the **example responses of its
specification**. It needs no account, keeps no state and never touches tenant data, so you can
explore the API, build a first prototype or test your error handling before you have a key.

| Module | Sandbox base URL |
|---|---|
| HR | `https://developers.mbcom.cloud/sandbox/hr` |
| Desk | `https://developers.mbcom.cloud/sandbox/desk` |
| Forge | `https://developers.mbcom.cloud/sandbox/forge` |
| Comms | `https://developers.mbcom.cloud/sandbox/comms` |
| Trade, DMS, master data, CRM | `https://developers.mbcom.cloud/sandbox/trade`, `…/dms`, `…/masterdata`, `…/crm` – these specs use full paths, e.g. `https://developers.mbcom.cloud/sandbox/dms/api/dms/v1/documents` |
| Workflow, search | `https://developers.mbcom.cloud/sandbox/workflow`, `https://developers.mbcom.cloud/sandbox/search` |
| Flows | `https://developers.mbcom.cloud/sandbox/flows` – full paths, e.g. `https://developers.mbcom.cloud/sandbox/flows/api/flows/v1/flows` |

## Try it in the browser

Every [reference page](/reference/desk) has a **Test Request** button. The sandbox is the
pre-selected server and a placeholder token is filled in, so a click sends the request.

## Try it with curl

```bash
# key exchange: any key starting with cck_ works
curl -X POST 'https://developers.mbcom.cloud/sandbox/hr/auth/token' -H 'Authorization: Bearer cck_sandbox'

# any bearer token works for the module APIs
curl 'https://developers.mbcom.cloud/sandbox/desk/items?limit=5' -H 'Authorization: Bearer sandbox'

curl -X POST 'https://developers.mbcom.cloud/sandbox/desk/items' \
  -H 'Authorization: Bearer sandbox' -H 'Content-Type: application/json' \
  --data '{"spaceId": "SUP", "title": "Drucker im 2. OG druckt nicht"}'
```

## What the sandbox checks

It refuses what a real service would refuse first, with the real [error shape](/guides/errors):

| Check | Answer |
|---|---|
| unknown route | `404 not_found`, wrong method `405` |
| missing `Authorization` header | `401 unauthorized` (`invalid_api_key` for the key exchange) |
| missing required query or header parameter | `400 invalid` with `field` |
| missing or invalid JSON body, missing required top-level field | `400 invalid` with `field` |

Everything else succeeds with the documented example. Write requests echo the top-level fields you
sent, so a created item has your title.

To test your error handling, ask for any documented response with the `Prefer` header:

```bash
curl -X PATCH 'https://developers.mbcom.cloud/sandbox/desk/items/1234' \
  -H 'Authorization: Bearer sandbox' -H 'Content-Type: application/json' \
  -H 'Prefer: code=409' --data '{"version": 1, "title": "x"}'
```

Answers carry `X-Sandbox: true`. The sandbox is rate limited per client address.

## Limits

The sandbox does not check permissions, does not validate values (enum values, formats, lengths),
does not know rules that depend on the caller (a desk item update without `version` succeeds here,
while the API answers `400` to everyone but an automation – ask for it with `Prefer: code=400`)
and does not remember anything: a `GET` after a `POST` will not show your item. Use a staging tenant
or a test tenant in production for end-to-end tests.
