Revoke API key

Revokes the key with the given id (the ak_-prefixed handle, not the secret). Revocation is immediate — requests using the revoked secret are rejected from then on — and idempotent: re-revoking returns 204 and keeps the original revoked_at. Master-token only (403 with code unauthorized for API-key callers). Requires the Postgres-backed key store (DATABASE_URL); without it this route is not registered and returns 404 route_not_found.

DELETE/v1/api-keys/{id}

Authorization

AuthorizationBearer token · headerrequired

`Authorization: Bearer <token>` — either the static master token (`ORCH_AUTH_TOKEN`) or a revocable API key issued via /v1/api-keys (API keys require Postgres; without a database only the master token is accepted). Master-only surfaces (exec, attach, API key management) refuse API keys with 403. An expired key is refused with 401 like an unknown one. A key minted with `scopes` reaches only the hitl routes (`/v1/interventions`, `/v1/hitl/*`, and POST /v1/api-keys to mint a narrower key). Any other route is 403 code `forbidden`, reason `env_scope`, except an `/v1/environments/{vmId}` route for an environment the key does not cover, which is 404 so the key cannot probe which environments exist. **Authentication can be disabled entirely.** When neither `ORCH_AUTH_TOKEN` nor an API key store (`DATABASE_URL`) is configured — the default local-development posture — the bearer middleware becomes a pass-through: every operation this document marks as secured is reachable with no credentials, requests carry no principal, and master-only surfaces therefore admit everyone. Never run that configuration on a reachable network; set `ORCH_REQUIRE_AUTH=true` to make the orchestrator refuse to start without a master token.

fuse_sessionAPI key · cookierequired

HttpOnly session cookie set by POST /login for browser callers. Consulted only when no Authorization header is present.

Path parameters

idstringrequired

API key id from create or list (prefix `ak_`).

Responses

204Key revoked (or already revoked).

401Missing or invalid bearer token.

errorobjectrequired

Show properties

codestringrequired

Stable machine-readable code. `route_not_found` (404) means the URL matches no route this server exposes — usually a wrong host, port, or path prefix — as opposed to `not_found`, where the route exists but the resource does not. `forbidden` is emitted by CIDR-allowlist rejections and by hitl access checks, which set `details.reason` (see the Forbidden response); master-only refusals (exec, attach, listing and revoking API keys) return 403 with code `unauthorized`.

Allowed:not_foundroute_not_foundconflictinvalid_argumentunauthorizedforbiddenunavailableinternalunimplementedlocked

messagestringrequired

Human-readable description.

detailsobject

Optional stable, non-sensitive metadata (e.g. ids, counts). Omitted when empty. A 403 `forbidden` from a hitl access check carries `reason` (`missing_scope`, `env_scope`, `self_approval`, `actor_required`, `actor_mismatch`, `actor_not_allowed`, `mint_escalation`, `hitl_denied`), plus `scope` for `missing_scope`, and `gate` and `intervention_id` for `hitl_denied`. A 423 `locked` carries `intervention_id` and `kind` (`takeover` or `stall`).

403The caller authenticated, but may not make this request. Master-only surfaces (exec, attach, listing and revoking API keys) refuse API keys; those 403 bodies carry code `unauthorized`. CIDR allowlist rejections return 403 with code `forbidden` and no reason. Access checks on the hitl routes and scoped keys return 403 with code `forbidden` and `details.reason` set to one of: - `missing_scope`: the key lacks the scope the route needs (`details.scope` names it). Full-access keys never hold `hitl:decide`, `hitl:secret`, `hitl:takeover` or `hitl:act-as`. - `env_scope`: a scoped key called a route outside the hitl routes. - `self_approval`: the key or actor that raised an intervention tried to decide it. - `actor_required`: the environment sets `require_actor` and the decision names no pinned or asserted actor. - `actor_mismatch`: `Fuse-Actor` differs from the key's pinned actor. - `actor_not_allowed`: `Fuse-Actor` sent by a key without `hitl:act-as`. - `hitl_denied`: a hitl gate in `deny` mode, or a gate's decider, refused an exec, lifecycle or computer action, or an edit matched a `deny` gate. `details.gate` names the gate and `details.intervention_id` the terminal record; the message is the gate's `reason`. - `mint_escalation`: a scoped key tried to mint a key wider than itself.

errorobjectrequired

Show properties

codestringrequired

Allowed:not_foundroute_not_foundconflictinvalid_argumentunauthorizedforbiddenunavailableinternalunimplementedlocked

messagestringrequired

Human-readable description.

detailsobject

404Resource does not exist. Note the distinct code `route_not_found`, returned when the URL matches no registered route at all (wrong host, port, or path prefix) rather than a known route with a missing resource.

errorobjectrequired

Show properties

codestringrequired

Allowed:not_foundroute_not_foundconflictinvalid_argumentunauthorizedforbiddenunavailableinternalunimplementedlocked

messagestringrequired

Human-readable description.

detailsobject

500Unexpected server error.

errorobjectrequired

Show properties

codestringrequired

Allowed:not_foundroute_not_foundconflictinvalid_argumentunauthorizedforbiddenunavailableinternalunimplementedlocked

messagestringrequired

Human-readable description.

detailsobject

Request

curl -X DELETE "http://localhost:8080/v1/api-keys/string" \
  -H "Authorization: Bearer YOUR_TOKEN"

const response = await fetch("http://localhost:8080/v1/api-keys/string", {
  method: "DELETE",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN"
  }
});

import requests

response = requests.delete(
    "http://localhost:8080/v1/api-keys/string",
    headers={
        "Authorization": "Bearer YOUR_TOKEN"
    },
)

Response

Key revoked (or already revoked).