What the sandbox can judge, and what it cannot
This page answers one question only: can these APIs be integrated?
1. What the sandbox is, and is not
| Column | Content |
|---|---|
| Is | A standalone demonstration environment, built to judge one thing: whether these APIs can be integrated. |
| Is | A chain you can actually call: device registration, heartbeat, device record, model catalogue, billing events, usage roll-up and on-demand collection all work on the sandbox (listed one by one in Section 2). |
| Is not | Not a production environment; the data is mock; it is not an SLA. The sandbox can be reset at any time, and old keys stop working immediately after a reset. |
| Is not | Not real devices and not real certificates: collection aggregates demonstration data, and a "certificate reference" is only a reference string — no real certificate is issued. |
| Is not | Not the full API surface: audit query, audit verification and device certificate are not exposed on the sandbox (see Section 2). |
2. Host and endpoint list
Host: sandbox.neutralorbit.com (HTTPS). The API host and the website host are two different sites — calling an API path on neutralorbit.org returns 404: a different site, not a broken API.
| Method | Path | Expected code | What this one is for |
|---|---|---|---|
| GET | /healthz | 200 | Public probe: answers "is the service alive". No credential, no business data. |
| GET | /readyz | 200 | Public probe: readiness. Anything other than 200 means "do not come in right now", not a fault. |
| GET | /meta | 200 | Public probe: service identity (service name, version, legal entity, boundary statement). |
| POST | /v1/devices | 401 | Device registration and activation. |
| POST | /v1/devices/{device_id}/heartbeat | 401 | Device heartbeat. |
| POST | /v1/billing/events | 401 | Billing event reporting. |
| GET | /v1/device-models | 401 | Model catalogue (read-only). |
| POST | /v1/device-models | 401 | Add a model. Requires admin; the sandbox never issues admin, so even with a key this returns 403. |
| GET | /v1/devices/{device_id} | 401 | Device record (read-only). |
| PATCH | /v1/devices/{device_id} | 401 | Change a device record (swap model / suspend / enable). |
| GET | /v1/usage | 401 | Usage roll-up (since / until / group_by=day|device|metric). |
| POST | /v1/usage/collect | 401 | Trigger one collection (aggregates demonstration data; no real device is contacted). |
| GET | /v1/usage/collect/{job_id} | 401 | Collection job status (read-only). |
| GET | /v1/audit | 404 | Audit query. Not exposed on the sandbox; on the production API it is 401 without a credential. |
| GET | /v1/audit/verify | 404 | Audit verification. Not exposed on the sandbox; on the production API it is 401 without a credential. |
| GET｜POST | /v1/devices/{device_id}/certificate | 404 | Device certificate reference. Not exposed on the sandbox; on the production API it is 401 without a credential. |
| GET | /proof/verify | 404 | Offline proof-bundle verification. Exposed on neither the production API nor the sandbox. |
The sandbox exposes fewer paths than the production API: audit query, audit verification and device certificate return 401 on the production API and 404 on the sandbox. This table is the reference: a 404 here means the path is not exposed, not that you called it wrong.
3. How to get a key
Keys are issued on written request: state your organisation name, a contact, the endpoints you need and the period you need, and send it to partners@neutralorbit.com. We review it manually and then issue the key; the period never exceeds 7 days.
There is no online application page and no instant activation.
The confirmation letter states the scope issued to you, the expiry time and the call ceiling. No confirmation letter means no approval — do not try someone else's key and do not keep re-sending.
- List the endpoints you need as "method + path", e.g. GET /v1/device-models, POST /v1/usage/collect.
- Give a start and end date, ≤ 7 days; the key expires on time and is not auto-renewed.
- Never use an example key that appears in any document: examples demonstrate the shape, they are not real keys. Real keys arrive only in the confirmation letter.
4. The four limits on a key
| # | Limit | What it means |
|---|---|---|
| 1 | One-off | One key goes to one POC of one organisation; not renewed, not inherited, not transferred. For another round, apply again. |
| 2 | Valid ≤7 days | Default 7 days, shortest by the hour; it expires on time and is not auto-renewed. |
| 3 | One scope, never admin | One key carries one scope only (one of devices:read / devices:write / usage:read / usage:collect / billing:write). |
| 4 | Rate-limited | The confirmation letter states the call ceiling for your key; if you hit it, wait — do not route around it with another key. |
The add-model endpoint (POST /v1/device-models) requires admin, and the sandbox never issues admin — so that endpoint always returns 403 on the sandbox.
5. How to read failure codes
| Code | Meaning | What to do |
|---|---|---|
| 401 | No identity presented | Send the credential (Authorization: Bearer … or X-Api-Key: …). |
| 403 | Identity fine, permission insufficient | This scope is not enough — use another endpoint or request another scope. |
| 404 | This path is not exposed | The service is not broken; see the endpoint list above. |
| 429 | Five consecutive failures with the same credential lock it for 15 minutes | Wait (Retry-After tells you how many seconds) — do not keep trying. |
6. Three self-tests (no key needed)
- Call
/healthzand look for 200 — the service is alive. - Call any write endpoint without a credential and look for 401 — authentication really is blocking.
- Call a path that does not exist and look for 404 — the allow-list really is blocking.
curl -sS -i https://sandbox.neutralorbit.com/healthz
curl -sS -i -X POST https://sandbox.neutralorbit.com/v1/devices -H "Content-Type: application/json" -d '{}'
curl -sS -i https://sandbox.neutralorbit.com/nope
7. Disclaimer
The sandbox is a demonstration environment; the data is mock; it is not an SLA; we make no commitment about sandbox availability.
- The sandbox may be reset at any time; after a reset old keys stop working immediately. Rate thresholds may change; APIs may change.
- The confirmation letter you receive and the bundled
openapi.yamlprevail. - No reading taken on the sandbox may be used as a basis for acceptance, settlement or any external commitment.