# Collect an approved sandbox key

`POST /sandboxes/token`

The second half of `POST /sandboxes`. Takes no credential but the `deviceCode`. Answers `status: "pending"` until the person approves, then `status: "approved"` with the `apiKey`, **exactly once**: the next call is `404`. If the person declines, the answer is `403 authorization_denied`, also once: tell them, and do not start another authorization by yourself. An authorization that expired, or a code that is not known, is `404`; start again with `POST /sandboxes`.

## Body

| Field | Type | | Description |
|---|---|---|---|
| `deviceCode` | string | **required** | From `POST /sandboxes`. |

## Response

`200`: `{ "ok": true, … }`

| Field | Type | | Description |
|---|---|---|---|
| `ok` | boolean | **required** |  |
| `status` | string | **required** |  One of: `pending`, `approved`. |
| `interval` | integer |  | While pending: seconds to wait before the next poll. |
| `mode` | string |  | When approved. One of: `sandbox`. |
| `apiKey` | string |  | When approved: the `bk_test_` key, shown here once. |
| `keyPrefix` | string |  | When approved: the first characters of the key. |
| `apiBase` | string |  |  |
| `mcpUrl` | string |  |  |
| `docs` | string |  |  |

Errors: `400`, `403`, `404`, `429`, `503`. Every failure answers `{ "error", "reason", "hint", "param", "doc_url", "retryable", "request_id" }`: branch on `reason`, and read `hint` for what to change (https://docs.billos.co.il/errors.md).

## Examples

### cURL

```bash
curl -X POST "$BASE/sandboxes/token" \
  -H "Content-Type: application/json" \
  -d '{
    "deviceCode": "string"
  }'
```
### Node

```node
const res = await fetch(`${BASE}/sandboxes/token`, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "deviceCode": "string"
  }),
})
const data = await res.json()
if (!data.ok) throw new Error(data.reason)
```
### Python

```python
import requests
res = requests.post(
    f"{BASE}/sandboxes/token",
    json={
      "deviceCode": "string"
    },
)
data = res.json()
```