Sandbox

A sandbox key is an ordinary API key with two differences: it acts in an isolated partition of your organization, and it cannot leave it. That is what makes it safe to hand to a test suite. Nothing a sandbox key writes touches your real graph, and nothing it reads can reach a real subject.

Minting one

curl -X POST https://api.get-exo.com/v1/sandbox/keys \
  -H "X-Exo-API-Key: $EXO_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"label": "CI"}'

The response carries the plaintext exactly once, like any minted key.

{
  "id": "3f1c0a...",
  "apiKey": "exo_sandbox_...",
  "label": "CI",
  "scopes": ["read", "write"],
  "subject": "__sandbox__"
}

Four things are fixed and not negotiable through the request:

Property	Value	Why
Prefix	`exo_sandbox_`	Recognisable on sight, in a log or a config file.
Scopes	`read` and `write`	Not caller-selectable. A test key must never mint keys, provision subjects or erase real data.
Lifetime	30 days	The pitch is a throwaway credential for a throwaway partition. It expires.
Subject	`__sandbox__`	The reserved partition it is bound to.

Minting needs the admin scope. See POST /v1/sandbox/keys.

The containment rule

A sandbox key presenting X-Exo-Subject for anything but its own partition is refused with 403 permission_denied. Without that rule “sandbox” would be a label rather than a boundary: one leaked test key could read, and once exports shipped, dump, every provisioned subject in the organization. The check asks the database rather than trusting the key prefix, so it holds even for a key minted through another route. A sandbox key also cannot mint API keys, for the same reason.

Resetting it

curl -X POST https://api.get-exo.com/v1/sandbox/reset \
  -H "X-Exo-API-Key: $EXO_ADMIN_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

The response reports what went:

{
  "subject": "__sandbox__",
  "rowsDeleted": 1284,
  "tablesCleared": 9,
  "tablesSkipped": 0,
  "jobsDeleted": 12,
  "keysRetained": 2,
  "orphansDeleted": 0
}

The reset keeps the sandbox user and its keys. That is the point: your test credential keeps working against a now-empty partition, so a suite does not have to re-mint between runs. Running it on an already-empty sandbox is a no-op that returns zeroes. Reset is replay-safe. A resubmitted Idempotency-Key returns the original counts rather than running the wipe again.

What reset does not clear

Reset removes rows it can attribute to the sandbox partition. Some derived structure has no attribution: domains the sandbox content helped form, segmentation rows, and clustered agent patterns are organization-wide aggregates, and deleting them would take a real user’s cognition with them. Those are left in place, deliberately. If you genuinely need a clean slate for the whole organization, that is POST /v1/purge with scope: "org", which is a two-phase destructive ceremony rather than a test convenience.

Routes

Route	What it does
`POST /v1/sandbox/keys`	Mint a sandbox key. Plaintext shown once. Not idempotency-replayable.
`GET /v1/sandbox/keys`	List sandbox keys, active and revoked.
`DELETE /v1/sandbox/keys/{key_id}`	Revoke one. Idempotent 204, even for an unknown id.
`POST /v1/sandbox/reset`	Wipe the partition, keep the keys.

All four require admin.

One conflict to know about

__sandbox__ is a reserved subject id. If it was already provisioned as an ordinary subject, the sandbox cannot claim it without colliding with real data, and the routes refuse with 409 sandbox_subject_conflict rather than proceeding.

Authentication

How keys are minted, presented and revoked.

Scopes

Why a sandbox key is capped at read and write.

Start

Building with Exo

Platform

Minting one

The containment rule

Resetting it

What reset does not clear

Routes

One conflict to know about

Next

Authentication

Scopes

​Minting one

​The containment rule

​Resetting it

​What reset does not clear

​Routes

​One conflict to know about

​Next

Authentication

Scopes

Minting one

The containment rule

Resetting it

What reset does not clear

Routes

One conflict to know about

Next