Skip to content
Fuse
Esc
↑↓navigate↵open⌘Jpreview

Create API key

Mints a new revocable API key. key is the raw secret (prefix fuse_sk_) and appears only in this response; it cannot be recovered afterward — only its SHA-256 is stored. An empty body creates an unlabeled key; only a present-but-malformed body is 400. Master-token only: a caller authenticated with an API key receives 403, and the 403 body carries code unauthorized (not a separate forbidden code). Auth is never disabled on this route: it exists only when the Postgres key store is configured, and that same store makes bearer auth mandatory, so every request reaching this handler carries a principal. Requires the Postgres-backed key store (DATABASE_URL); without it this route is not registered and returns 404 route_not_found.

Note that ORCH_AUTH_TOKEN unset with DATABASE_URL set is permitted (unless ORCH_REQUIRE_AUTH=true), and in that configuration there is no master credential at all: every caller authenticates as an API key and therefore receives 403 unauthorized here. Configure a master token to use this route.

POST/v1/api-keys
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. **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.
or
fuse_sessionAPI key · cookierequired
HttpOnly session cookie set by POST /login for browser callers. Consulted only when no Authorization header is present.
Request body
application/json
labelstring
Optional operator memory aid ("ci", "partner-acme").
Responses
201Key created; `key` is shown exactly once.
idstringrequired
Public handle, prefix `ak_`. Used to revoke; not the secret.
labelstring
Optional operator memory aid. Omitted when empty.
created_atstring<date-time>required
last_used_atstring<date-time>
Omitted (not null) until the key first authenticates. Best-effort bump.
revoked_atstring<date-time>
Omitted (not null) while the key is live.
keystringrequired
Raw secret, prefix `fuse_sk_`. Shown exactly once; only its SHA-256 is stored.
400Malformed request.
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 only by CIDR-allowlist rejections; master-only refusals (exec, attach, API key management) return 403 with code `unauthorized`.
Allowed:not_foundroute_not_foundconflictinvalid_argumentunauthorizedforbiddenunavailableinternalunimplemented
messagestringrequired
Human-readable description.
detailsobject
Optional stable, non-sensitive metadata (e.g. ids, counts). Omitted when empty.
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 only by CIDR-allowlist rejections; master-only refusals (exec, attach, API key management) return 403 with code `unauthorized`.
Allowed:not_foundroute_not_foundconflictinvalid_argumentunauthorizedforbiddenunavailableinternalunimplemented
messagestringrequired
Human-readable description.
detailsobject
Optional stable, non-sensitive metadata (e.g. ids, counts). Omitted when empty.
403The caller authenticated, but not as the master operator. Master-only surfaces (exec, attach, API key management) refuse API keys; those 403 bodies carry code `unauthorized`. CIDR allowlist rejections also return 403 but with code `forbidden`.
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 only by CIDR-allowlist rejections; master-only refusals (exec, attach, API key management) return 403 with code `unauthorized`.
Allowed:not_foundroute_not_foundconflictinvalid_argumentunauthorizedforbiddenunavailableinternalunimplemented
messagestringrequired
Human-readable description.
detailsobject
Optional stable, non-sensitive metadata (e.g. ids, counts). Omitted when empty.
404No Postgres key store is configured, so this route is not registered; the fallback handler answers with code `route_not_found`.
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 only by CIDR-allowlist rejections; master-only refusals (exec, attach, API key management) return 403 with code `unauthorized`.
Allowed:not_foundroute_not_foundconflictinvalid_argumentunauthorizedforbiddenunavailableinternalunimplemented
messagestringrequired
Human-readable description.
detailsobject
Optional stable, non-sensitive metadata (e.g. ids, counts). Omitted when empty.
500Unexpected server error.
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 only by CIDR-allowlist rejections; master-only refusals (exec, attach, API key management) return 403 with code `unauthorized`.
Allowed:not_foundroute_not_foundconflictinvalid_argumentunauthorizedforbiddenunavailableinternalunimplemented
messagestringrequired
Human-readable description.
detailsobject
Optional stable, non-sensitive metadata (e.g. ids, counts). Omitted when empty.
Request
curl -X POST "http://localhost:8080/v1/api-keys" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "label": "string"
}'
Response
{
  "id": "string",
  "label": "string",
  "created_at": "2024-01-01T00:00:00Z",
  "last_used_at": "2024-01-01T00:00:00Z",
  "revoked_at": "2024-01-01T00:00:00Z",
  "key": "string"
}