ZSC Admin API — /api/zsc/*

The ZSC admin API is the operator surface for the framework's encrypted secret store. Every endpoint is admin-gated (requireAdmin middleware — admin JWT cookie required), every call produces a row in audit_log, and plaintext values are NEVER returned in any response. Operators read plaintext only via the internal ZeqContext.read() path (which writes its own audit row); the HTTP surface deals only in metadata + lifecycle operations.

Source: shared/api-core/src/routes/zscAdmin.ts. Background: ZSC Secure Context, ZSC Audit Trail.

Endpoints

Method	Path	Notes
GET	/api/zsc/list	All secrets, metadata only.
GET	/api/zsc/info/:name	Single secret metadata.
POST	/api/zsc/set	Upsert (create or replace).
POST	/api/zsc/rotate/:name	Re-encrypt with fresh IV.
POST	/api/zsc/grant/:name	Add ZID to permissions.
POST	/api/zsc/revoke/:name	Remove ZID from permissions.
GET	/api/zsc/audit/:name	Recent audit rows for this name.
POST	/api/zsc/probe-permission	Test whether a ZID can read, without exposing plaintext.
DELETE	/api/zsc/:name	Permanent removal.

Auth

All endpoints require the zeq_admin HMAC-signed JWT cookie. The middleware is requireAdmin (shared/api-core/src/middlewares/requireAdmin.ts). Sign in at /admin/ to obtain the cookie.

Reads from the public Pulse/orb surface do not use these routes — they call ZeqContext.read() directly with the caller's ZID. The admin API exists for operator lifecycle ops only.

Common error shape

All endpoints share the same error envelope:

{ "ok": false, "error": "ERROR_CODE", "detail": "optional human string" }

Common codes:

Status	error	Meaning
400	name required, value must be a string, value too large (>64KB), zid required	Input validation.
401	unauthorized	Admin cookie missing or invalid.
404	NOT_FOUND	Secret doesn't exist.
500	INTERNAL_ERROR	Backend failure — DB unreachable, encryption error, etc. Check api-core logs.

Companion surfaces

• CLI: pulse > context … — same operations, terminal interface
• Admin UI: /portal/secrets/ — same operations, web interface
• Bootstrap: Operate → ZSC Bootstrap — master-key + KMS adapter setup