HEXAGON_API_TOKEN and control-plane origin without /v1 in HEXAGON_API_URL. Do not place real secrets in command history, shared JSON fixtures or public evidence. Prepare any value-bearing request file in private storage and remove the plaintext copy when it is no longer needed.
Metadata and references
GET /v1/secrets returns 200, {secrets:[...]}, ordered by creation time ascending, without pagination. Deleted rows are excluded. Each entry contains id, name, version, enabled, created_at, updated_at; it contains neither value nor encrypted envelope.
GET /v1/secrets/{id} returns 200, those same fields plus:
Session references are derived from pinned connection IDs and current managed-secret linkage, not a full historical credential audit. A Session may appear more than once through different connections, and closed Sessions are not excluded. The bounded array has no next-page cursor. Do not interpret it as proof that no other dependencies exist.
404 secret_not_found.
Create
POST /v1/secrets accepts strict {name,value}. Name is a required 1–200-character string. Value is a required 1–32,768-character string without NUL; downstream credential protocols may apply further restrictions. Names are not normalized by trim in this schema.
Success returns 201, the metadata/detail object above, not the supplied plaintext. Storage uses the configured SecretStore inside the creation transaction. Name is not an idempotency key; repeated POSTs can create distinct Secrets.
Prepare secret-create.json privately with the actual name/value, then:
Patch and rotate
PATCH /v1/secrets/{id} accepts a strict object with optional name, value and enabled:boolean. Name/value retain creation constraints. Success returns 200, the current detail object. Omitted fields keep their previous values. There is no expected_version condition; the row lock serializes updates but does not detect stale client intent.
Invalidating connections means
enabled=false, status="draft", validation=null, connection version incremented. Enabling the Secret again does not automatically revalidate or enable the connections. These updates cover nondeleted managed-secret connection references; they do not rewrite pinned Session definitions. Existing access may fail because of availability/version checks. Plan revalidation and subsequent Session usage accordingly.
The following disables the Secret and invalidates its referencing connections:
Delete
DELETE /v1/secrets/{id} returns 204 without a response body. It rejects any nondeleted referencing connection or registered Harness image with 409 secret_in_use. Disablement alone does not remove a reference; inspect dependencies and use their supported lifecycle operations first.
404 secret_not_found; if the response was lost, use that tenant-scoped observation alongside your recorded identity to reconcile the deletion.
Malformed strict input returns 400 invalid_request; application tokens receive 403 owner_token_required; missing authentication receives 401. These operations do not by themselves validate credentials against a provider. Sources: managed Secret implementation, HTTP routes. The credential contract review used dummy values in isolated tenants with real encrypted PostgreSQL storage. It checked create/read/list/patch/delete, empty-patch version increments, rename preserving connection state, value rotation updating the protected copy and invalidating a controlled connection, same-value enabled invalidation, dependency deletion rejection, tenant/role boundaries and absence of plaintext in responses. Test rows were removed. No real external credential was rotated, and Harness-image dependencies or the bounded 200-row Session-reference query were not exercised by this run.
Read the version after a patch
Suppose a new Secret is version 1. Applying{} returns version 2 even though its visible name and enabled state stay the same. A name-only patch then returns version 3 and leaves referencing connection versions unchanged. A value patch returns version 4 and increments each nondeleted referencing connection version while disabling it and clearing validation. These version numbers illustrate a sequence with no other edits; read returned values in your own application.
Do not use the visible name or enabled flag to decide whether a lost patch already committed. Save the pre-change version and intended operation, inspect the returned/current Secret and affected connections, and reconcile before another update. There is no compare-and-swap precondition on this endpoint, so another editor can change the record between your read and write.
Next: credential rotation guide, HTTP overview.