DOCUMENTATIONv2

POST

Workspace Management

Secure new workspace

/api/v2/workspaces/{id}/custody-ceremonies

AUTHENTICATIONBearer token · workspaces:writeAUTHORITATIVE OWNERdark-meshCONTRACT 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

Prepare a workspace- and network-bound MPC custody ceremony under server-owned participant, threshold, recovery, and evidence policy.

WHEN THIS CALL IS USEFUL

Do not call this planning contract yet. When promoted, it belongs after workspace creation and policy selection but before participant enrollment, wallet activation, or signing authority.

OUTCOME · Planned custody preparation

What changes

No executable public mutation exists. A future success would create PREPARED commitments only—not a seed, active wallet, distributed share, signature, transaction, or value movement.

WHY IT MATTERS

Will establish immutable custody intent before any party handles shares or activation evidence.
Will prevent one workspace or network’s custody policy from being reused in another boundary.

ISOLATION + AUTHORITY

The future ceremony is immutably bound to workspace, network, purpose, participant policy, threshold policy, and recovery policy. All key and share material stays outside the public API.

BEFORE YOU CALL

Future workspaces:write and custody-administration authority.
A supported network, purpose, policy profile, recovery policy, fresh step-up, request signature, and Idempotency-Key.
An implemented operation in live production OpenAPI.

WHAT TO DO NEXT

Wait for implementation in live OpenAPI.
When available, follow the returned next_required_action rather than assuming enrollment or activation.

AGENT GUIDANCE

Do not register or invoke this operation while it remains planned.
Never synthesize participant policy or collect secret custody material; the authoritative owner must derive and retain those controls.
Treat PREPARED as the start of a separate ceremony, not as wallet activation or permission to sign.

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 workspaces:write scope.EXAMPLEBearer hc_live_…

Idempotency-KeyheaderRequired

ASCII string · 1–128Caller-generated key reused for every retry of the same logical mutation.EXAMPLElaunch-treasury-v1-001

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:

idpathRequired

authenticated workspace identifierWorkspace receiving the future custody wallet; must match bearer authority.EXAMPLEworkspace-01

network_idbodyRequired

supported network identifierMust match workspace custody policy.EXAMPLEhybrid-testnet

purposebodyRequired

TREASURY | SETTLEMENT | APPLICATION | RECOVERYSelects server-owned participant, threshold, custody, and recovery policy.EXAMPLETREASURY

wallet_labelbodyRequired

string · 2–160Presentation-safe wallet label; never an authority identifier.EXAMPLEPrimary treasury

policy_profilebodyRequired

approved custody-policy codeFresh server-owned policy; callers never select participants or submit public keys.EXAMPLEMPC_STANDARD_3_OF_5

recovery_policybodyRequired

approved recovery-policy codePre-reviewed recovery posture that cannot bypass participant, delay, approval, or evidence controls.EXAMPLEGOVERNED_RECOVERY_V1

step_up_tokenbodyRequired

purpose-bound tokenFresh CUSTODY_CEREMONY_CREATION authorization.EXAMPLEhcsu_…

REQUEST

JSON body example

{
  "network_id": "hybrid-testnet",
  "purpose": "TREASURY",
  "wallet_label": "Primary treasury",
  "policy_profile": "MPC_STANDARD_3_OF_5",
  "recovery_policy": "GOVERNED_RECOVERY_V1",
  "step_up_token": "hcsu_…"
}

RESPONSES

Status and payload examples

201PREPARED ceremony and immutable policy commitments returned; no wallet is active and no key material is disclosed.Not executable · JSON RESPONSE+

{
  "ceremony_uuid": "ceremony-01",
  "state": "PREPARED",
  "network_id": "hybrid-testnet",
  "purpose": "TREASURY",
  "participant_policy_commitment": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "threshold_policy_commitment": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
  "recovery_policy_commitment": "cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc",
  "wallet_active": false,
  "key_material_disclosed": false
}

INTEGRATION DECISION

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 owner-scoped wallet inventory, custody policy, balances, intents, reservations, transactions, and receipts through an implemented operation.
ESCALATE WHEN: Escalate when funds, reservations, transaction digests, or MPC state remain ambiguous after authoritative wallet and network reconciliation.

200Equivalent prepared ceremony returned idempotently.Not executable · JSON RESPONSE+

{
  "ceremony_uuid": "ceremony-01",
  "state": "PREPARED",
  "idempotent": true
}

INTEGRATION DECISION

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 owner-scoped wallet inventory, custody policy, balances, intents, reservations, transactions, and receipts through an implemented operation.
ESCALATE WHEN: Escalate when funds, reservations, transaction digests, or MPC state remain ambiguous after authoritative wallet and network reconciliation.

400A field, signed header, step-up token, or Idempotency-Key is malformed.Not executable · JSON RESPONSE+

{
  "code": "invalid_custody_ceremony",
  "message": "A field, signed header, step-up token, or Idempotency-Key is malformed."
}

INTEGRATION DECISIONinvalid_custody_ceremony

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 owner-scoped wallet inventory, custody policy, balances, intents, reservations, transactions, and receipts through an implemented operation.
ESCALATE WHEN: Escalate when funds, reservations, transaction digests, or MPC state remain ambiguous after authoritative wallet and network reconciliation.

401The bearer credential is invalid.Not executable · JSON RESPONSE+

{
  "code": "invalid_credentials",
  "message": "The bearer credential is invalid."
}

INTEGRATION DECISIONinvalid_credentials

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 owner-scoped wallet inventory, custody policy, balances, intents, reservations, transactions, and receipts through an implemented operation.
ESCALATE WHEN: Escalate when funds, reservations, transaction digests, or MPC state remain ambiguous after authoritative wallet and network reconciliation.

403The principal lacks workspaces:write, custody administration, or fresh step-up.Not executable · JSON RESPONSE+

{
  "code": "custody_ceremony_forbidden",
  "message": "The principal lacks workspaces:write, custody administration, or fresh step-up."
}

INTEGRATION DECISIONcustody_ceremony_forbidden

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 owner-scoped wallet inventory, custody policy, balances, intents, reservations, transactions, and receipts through an implemented operation.
ESCALATE WHEN: Escalate when funds, reservations, transaction digests, or MPC state remain ambiguous after authoritative wallet and network reconciliation.

404The workspace or policy profile is not owner-visible.Not executable · JSON RESPONSE+

{
  "code": "custody_policy_not_found",
  "message": "The workspace or policy profile is not owner-visible."
}

INTEGRATION DECISIONcustody_policy_not_found

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 owner-scoped wallet inventory, custody policy, balances, intents, reservations, transactions, and receipts through an implemented operation.
ESCALATE WHEN: Escalate when funds, reservations, transaction digests, or MPC state remain ambiguous after authoritative wallet and network reconciliation.

409Workspace, network, policy, active-ceremony, or Idempotency-Key state conflicts.Not executable · JSON RESPONSE+

{
  "code": "custody_ceremony_conflict",
  "message": "Workspace, network, policy, active-ceremony, or Idempotency-Key state conflicts."
}

INTEGRATION DECISIONcustody_ceremony_conflict

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 owner-scoped wallet inventory, custody policy, balances, intents, reservations, transactions, and receipts through an implemented operation.
ESCALATE WHEN: Escalate when funds, reservations, transaction digests, or MPC state remain ambiguous after authoritative wallet and network reconciliation.

422Purpose, participant-domain, threshold, recovery, compliance, or network policy rejected preparation.Not executable · JSON RESPONSE+

{
  "code": "custody_ceremony_rejected",
  "message": "Purpose, participant-domain, threshold, recovery, compliance, or network policy rejected preparation."
}

INTEGRATION DECISIONcustody_ceremony_rejected

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 owner-scoped wallet inventory, custody policy, balances, intents, reservations, transactions, and receipts through an implemented operation.
ESCALATE WHEN: Escalate when funds, reservations, transaction digests, or MPC state remain ambiguous after authoritative wallet and network reconciliation.

503Workspace, Dark Mesh, participant registry, policy, or evidence ownership is unavailable.Not executable · JSON RESPONSE+

{
  "code": "custody_ceremony_unavailable",
  "message": "Workspace, Dark Mesh, participant registry, policy, or evidence ownership is unavailable."
}

INTEGRATION DECISIONcustody_ceremony_unavailable

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 owner-scoped wallet inventory, custody policy, balances, intents, reservations, transactions, and receipts through an implemented operation.
ESCALATE WHEN: Escalate when funds, reservations, transaction digests, or MPC state remain ambiguous after authoritative wallet and network reconciliation.

OPERATIONAL NOTES

Security and lifecycle guarantees

Reviewed planning contract: do not call until present in live production OpenAPI.
Dark Mesh resolves participants, distinct operator domains, threshold, algorithms, attestation, and recovery controls. Never send entropy, mnemonic words, seeds, private keys, MPC shares, signing nonces, passwords, password files, or operator credentials.
PREPARED does not derive or activate a wallet, distribute shares, authorize signing, or move value. Enrollment, attestation, activation, signing, and settlement remain separate.
After an ambiguous result, re-read the ceremony inventory before retrying an equivalent body and Idempotency-Key.

UPGRADING FROM V1

Legacy calls replaced by this operation

If you maintain an older integration, use this map to find the V2 replacement. Do not translate the old request field-for-field: rebuild it from the V2 parameters and schemas above because identity, authorization, replay protection, and response semantics may have changed.

POST/api/v1/workspaces/secureWORKSPACE: Secure new Workspace

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 ↗