TEE Docker API reference

Everything shared by every endpoint lives here — base URL, authentication, the error shape, and the full route list — so the per-resource pages can stay short.

Base URL

Examples on this page use $API_URL. Set it once, with the /v1 prefix included — every route lives under it:

export API_URL=https://<your-api-host>/v1

Every route is prefixed with /v1, and request bodies are JSON needing content-type: application/json. Every example across this reference uses $API_URL, so set it once as above.

Authentication

Three tiers, plus GET /v1/health, which takes no credentials at all. Which tier a route takes is stated on every endpoint.

-H "X-Api-Key: $API_KEY" -H "X-Api-Secret: $API_SECRET"

-H "Authorization: Bearer $TOKEN"

-H "X-Admin-Key: $ADMIN_KEY"

Scopes

Most workspace-token routes additionally require a scope: read, write, sign, or export. A valid token used outside its scopes returns 403 with scope_denied. See Scopes and permissions.

Five routes are deliberately exempt and accept any token whatever scopes it carries: token refresh and revoke, account lock and unlock, and token introspection (whoami).

Error shape

Every error, from every route, has one shape:

{
  "error": {
    "code": "account_not_found",
    "message": "…",
    "status": 404,
    "requestId": "…"
  }
}

Branch on error.code, never on message — messages are for humans and may change. Keep requestId when reporting a problem to your operator.

Some codes add an optional error.details object alongside those four fields. It is opt-in per code rather than universal, so treat it as absent unless the code’s own documentation says otherwise.

The full catalog of codes, grouped by status, is on the Errors page.

Request tracing

Send your own correlation id and it will be echoed back:

-H "X-Request-ID: my-trace-id-123"

Accepted when it is 1–128 characters of letters, digits, dots, underscores, or hyphens. If it is missing or unsafe, the service generates a safe one instead. Either way the id appears in the response header and in error.requestId.

Status codes

Response headers

Two headers carry information back. They are also the only two exposed to cross-origin script, so a browser client can read these and nothing else.

The endpoints

Health lives on this page, under Check health. Every other resource has its own reference page:

Every route

This is the whole published surface — thirty-six routes, and nothing else is served. Token means a workspace token or a scoped API key; the scope column names the scope it must carry. Admin means the super-admin X-Admin-Key.

Check health

Liveness only. No authentication.

GET /v1/health

curl "$API_URL/health"

{ "status": "ok" }

A healthy service answers 200. Anything else — a connection failure, a non-200, or a body that is not {"status":"ok"} — means the instance is not ready to serve. During a graceful shutdown it answers 503 with {"status":"shutting_down"} — a distinct, expected drain state, not a crash, so a probe can tell the two apart.