Skip to main content
Managed Secrets store reusable credential values in the control plane. All five routes require an owner identity and tenant ownership. They do not reveal stored plaintext through read responses. Use ordinary Session variables only for values that Agent processes may read; these are different mechanisms. Examples assume a backend owner token in 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.
Missing, deleted or foreign Secret returns 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:
If the response is lost, inspect metadata before deliberately creating another. There is no endpoint for recovering plaintext from this response family.

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:
For value rotation, use a private request file with the new value instead of putting it in the command. Repeated patches are not harmless idempotent replays: they increment versions and can repeatedly invalidate connections. After a lost response, inspect versions/readiness before retrying. A successful control-plane update does not revoke the previous credential at the external provider.

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.
Deletion is a soft delete: marks deleted_at, disables and increments version. It does not claim physical erasure of all encrypted history or provider-side credential revocation. A subsequent GET or repeated DELETE returns 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.