Keys and sandbox

What this family does

Keys are organization credentials. Minting returns the plaintext once and stores only its SHA-256 hash, which is also the id you list and revoke by. A key can never be minted with a scope its creator does not already hold. The sandbox routes mint exo_sandbox_ keys bound to an isolated partition, so you can exercise the API without touching real data, and wipe that partition when you are done.

Routes

Method	Path	Scope	What it does
`GET`	`/v1/keys`	any key	List API keys
`POST`	`/v1/keys`	any key	Mint an API key
`DELETE`	`/v1/keys/{key_id}`	any key	Revoke an API key
`GET`	`/v1/sandbox/keys`	`admin`	List sandbox keys
`POST`	`/v1/sandbox/keys`	`admin`	Mint a sandbox (test-mode) API key
`DELETE`	`/v1/sandbox/keys/{key_id}`	`admin`	Revoke a sandbox key
`POST`	`/v1/sandbox/reset`	`admin`	Wipe the sandbox partition

Headers that apply here

Neither header is declared as an OpenAPI parameter, so neither appears in the generated schema tables.

Idempotency-Key makes a retry safe on POST /v1/keys, POST /v1/sandbox/reset. See Idempotency.

The shape of a call

Mint a key.

curl -X POST https://api.get-exo.com/v1/keys \
  -H "X-Exo-API-Key: $EXO_KEY" \
  -H "Content-Type: application/json" \
  -d '{"label": "ci-pipeline", "scopes": ["read"]}'

import httpx

response = httpx.post(
    "https://api.get-exo.com/v1/keys",
    headers={"X-Exo-API-Key": EXO_KEY},
    json={"label": "ci-pipeline", "scopes": ["read"]},
)
plaintext = response.json()["apiKey"]  # shown once

const response = await fetch("https://api.get-exo.com/v1/keys", {
  method: "POST",
  headers: {
    "X-Exo-API-Key": process.env.EXO_KEY!,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ label: "ci-pipeline", scopes: ["read"] }),
});
const { apiKey } = await response.json(); // shown once

The response:

{
  "id": "6b86b273ff34fce19d6b804eff5a3f5747ada4eaa22f1d49c01e52ddb7875b4b",
  "apiKey": "exo_prod_9f2c41a8b7e04d3c8a1f6e2b5d90c743",
  "label": "ci-pipeline"
}

Traps

The plaintext is unrecoverable. There is no route that returns it again. Store it before you close the response. A key that is not yours is 404, not 403. That keeps key hashes unenumerable. Revoking your own already-revoked key is a 204, so retries are safe. Minting a sandbox key does not replay. A retried Idempotency-Key mints a fresh key, because persisting a live credential in the replay store would undo the hash-only-at-rest design. Sandbox keys are contained. Their scopes are fixed at read and write, and they cannot select another subject.

API reference

Base URL, authentication, and the conventions every route shares.

Errors

The problem envelope and the full code catalogue.

​What this family does

​Routes

​Headers that apply here

​The shape of a call

​Traps

​Related