DOCUMENTATIONv2

PATCH

Governance

Update safe policy

/api/v2/governance/safes/{safe_uuid}

AUTHENTICATIONBearer token · governance:writeAUTHORITATIVE OWNERgovernance-serviceCONTRACT AUTHORITYCapability registry · plannedSTATUSPlanned · not executable

PLANNING CONTRACT · NOT CALLABLE

This page describes intended capability and integration boundaries so people and agents can prepare safely. Do not send this request or register it as an executable tool. Wait until the capability registry marks it implemented-contract, then re-fetch the deployed OpenAPI document and build the request from that machine contract.

PURPOSE + BUSINESS CONTEXT

Planned capability: propose an owner or threshold change through the governed safe workflow.

WHEN THIS CALL IS USEFUL

Do not call or register this operation as an executable agent tool yet. Use this page to plan the future safe policy workflow; enable it only after the status becomes implemented-contract and the exact operation appears in deployed OpenAPI.

OUTCOME · Planned · Revise and reconcile

What changes

None today: this route is not executable. Its intended behavior is: no executable public policy update exists. A future promotion would retain a POLICY_CHANGE proposal for current-member approval while leaving the active policy unchanged until every configured threshold, delay, acceptance, and owner gate passes.

WHY IT MATTERS

Lets people and agents prepare for safe policy without falsely presenting roadmap scope as a live capability.
Gives people and agents a contract-backed way to advance safe policy.
Keeps deliberation, approval evidence, authority assignment, and threshold-signing participation explicit and auditable.

ISOLATION + AUTHORITY

Tenant, workspace, proposal, voter, authority assignment, quorum, custody participant, and signing-session boundaries remain separate. A proposal, recorded decision, assigned role, or ceremony request does not by itself activate a contract, produce a threshold signature, move value, or grant publisher, matching, or trading authority. This planning record grants no runtime authority, and only deployed OpenAPI can define an executable public contract.

BEFORE YOU CALL

First confirm that this operation is marked implemented-contract and exists in the currently deployed OpenAPI document; until then, no production request is valid.
Its capability-registry profile is provisional integration guidance, not an executable request schema.
Authenticate at the documented boundary: bearer+scope.
Treat the proposed safe_uuid (path), expected_version (body), reason (body), step_up_token (body) as planning input only; re-generate the request from deployed OpenAPI before making a call.
Use one Idempotency-Key only for retries of the same byte-equivalent logical mutation.
Resolve the current proposal or assignment version, eligible authority, quorum rule, and purpose-bound policy before relying on this result.

WHAT TO DO NEXT

Keep this operation disabled in clients, agents, SDKs, and workflow automation while it remains planned-contract.
Use the stated owner, lifecycle, authority boundary, and provisional safe policy profile to prepare requirements and conformance tests without sending a request.
Monitor the capability registry for implemented-contract, then re-fetch deployed OpenAPI and validate its exact security, parameters, schemas, responses, and agent metadata before enabling the integration.

AGENT GUIDANCE

Never call this planned contract, include it in an executable tool registry, or infer runtime availability from this readable page.
Its capability-registry profile is provisional integration guidance, not an executable request schema.
Use safe policy only for the purpose and lifecycle stage described by this operation; do not treat it as authority for an adjacent action.
Treat the proposed safe_uuid (path), expected_version (body), reason (body), step_up_token (body) as planning input only; re-generate the request from deployed OpenAPI before making a call.
Keep proposal creation, review, decision recording, quorum satisfaction, authority assignment, ceremony request, participant signing, execution, and finality as separate lifecycle facts.
After a timeout or conflict, read authoritative state before deciding whether an equivalent retry is safe.
When implementation lands, discard generated requests based on this planning record and rebuild them from the deployed OpenAPI operation.

MACHINE CONTRACT

This operation is a non-executable planning contract. Its capability-registry record defines the intended owner, parameters, responses, and integration boundary until an implemented Rust OpenAPI operation replaces it.

EXTENDED INTEGRATION GUIDANCE

Readable request and response reference

Examples describe the reviewed planning contract and remain non-executable until promoted into OpenAPI.

PARAMETERS

Headers, path, query, and body

NAMELOCATIONPRESENCETYPE / RULES / PURPOSE

AuthorizationheaderRequired

Bearer tokenCredential containing the governance:write scope.EXAMPLEBearer hc_live_…

Idempotency-KeyheaderRequired

ASCII string · 1–128Caller-generated key reused for every retry of the same logical mutation.EXAMPLEsafe-policy-change-safe-uuid-01-v3

Content-TypeheaderRequired

application/jsonSigned mutations accept canonical JSON only.EXAMPLEapplication/json

Content-DigestheaderRequired

RFC 9530 SHA-256 digestDigest of the exact transmitted body bytes.EXAMPLEsha-256=:47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU=:

Signature-InputheaderRequired

RFC 9421 signature parametersCovers @method, @path, content-digest, content-type, and idempotency-key; includes keyid, nonce, created, and expires.EXAMPLEsig1=("@method" "@path" "content-digest" "content-type" "idempotency-key");created=1786582800;expires=1786583100;nonce="01J…";keyid="machine-prod"

SignatureheaderRequired

Ed25519 HTTP Message SignatureSignature made by an active public key registered to the authenticated client.EXAMPLEsig1=:base64-signature:

safe_uuidpathRequired

workspace- and network-scoped safe identifierStable safe identifier discovered from the future owner inventory.EXAMPLEsafe-uuid-01

expected_versionbodyRequired

integer · ≥1Current active safe-policy version used for optimistic concurrency.EXAMPLE3

membersbodyOptional

member object[] · 2–32 uniqueOptional complete replacement member set using eligible member_id and active signing_key_id values; omission retains the current set.EXAMPLE[{"member_id":"profile-01JMEMBER01","signing_key_id":"hck_member_01"},{"member_id":"profile-01JMEMBER03","signing_key_id":"hck_member_03"}]

thresholdbodyOptional

integer · 1–replacement or current member countOptional replacement approval threshold; the resulting policy must remain satisfiable.EXAMPLE2

proposal_ttl_secondsbodyOptional

integer · 300–604800Optional replacement proposal approval window.EXAMPLE172800

execution_delay_secondsbodyOptional

integer · 0–604800Optional replacement post-approval delay.EXAMPLE7200

reasonbodyRequired

string · 8–500Attributed policy-change rationale retained with the proposal and evidence chain.EXAMPLEReplace a departing signer and extend the review window

step_up_tokenbodyRequired

one-use purpose-bound tokenFresh GOVERNANCE_SAFE_POLICY_CHANGE authorization bound to this safe and expected version.EXAMPLEhcsu_…

REQUEST

JSON body example

{
  "expected_version": 3,
  "members": [
    {
      "member_id": "profile-01JMEMBER01",
      "signing_key_id": "hck_member_01",
      "label": "Treasury lead"
    },
    {
      "member_id": "profile-01JMEMBER03",
      "signing_key_id": "hck_member_03",
      "label": "Compliance reviewer"
    }
  ],
  "threshold": 2,
  "proposal_ttl_seconds": 172800,
  "execution_delay_seconds": 7200,
  "reason": "Replace a departing signer and extend the review window",
  "step_up_token": "hcsu_…"
}

RESPONSES

Status and payload examples

501Profiled planning contract only; no authoritative public V2 safe-policy proposal owner exists and the operation is absent from live OpenAPI.Not executable · JSON RESPONSE+

{
  "code": "planned_contract",
  "message": "Governance safe policy changes are not available through V2."
}

INTEGRATION DECISIONplanned_contract

CALLER ACTION: Do not send this request or register it as an executable agent tool. Use the implemented alternatives linked by the module guide.
RETRY SAFETY: Do not retry on a timer. Re-fetch production OpenAPI and proceed only after this exact operation appears there.
STATE RECONCILIATION: No runtime state exists to reconcile for this planning contract. Continue from workspace governance proposals, approvals, signing handoffs, policy versions, and execution evidence through an implemented operation.
ESCALATE WHEN: Escalate when signer eligibility, threshold evidence, proposal version, or downstream execution state remains inconsistent after a fresh governance read.

OPERATIONAL NOTES

Security and lifecycle guarantees

expected_version, reason, and step_up_token are required, together with at least one replacement policy field. members is a complete replacement set, not a merge instruction.
A promoted 202 would mean proposal retention only. The active safe policy remains unchanged until current-member approvals, replacement-member acceptance, threshold, delay, and owner gates all pass.
On a future 409, re-read the safe and open proposals before forming a new intent. Never overwrite a concurrent change or silently merge a stale local member set.
Removing a member cannot erase historical approvals or evidence. This proposal cannot alter trading, matching, settlement, publisher, ingress, market status, or traffic, and it cannot replace a separate typed owning-domain binding ceremony.

DOCUMENTATION STATUS

This planned contract now defines its public parameters, authorization boundary, replay behavior, responses, and authoritative owner. It remains non-executable until its owner adapter and conformance tests are promoted into the Rust gateway.

Return to the V2 directory ↗