API and workflow reference

Scope

Decentralization Manager exposes an HTTP API from the same server that hosts its web application. Use this reference for routes, payloads, exact status values, error behavior, and retry boundaries.

The conceptual peer and coordinator model belongs in Decentralization Manager architecture overview. Product-wide troubleshooting and compatibility belong in Decentralization Manager compatibility, releases, and troubleshooting. This page keeps only API-specific workflow details and symptoms.

Treat the operator HTTP API as the public integration surface. The peer coordination protocol, Canton Admin API integration, Canton Ledger API integration, and Daml contract choices are implementation or platform interfaces unless a separate guide explicitly requires them. The repository binary is named dec-party-manager; public documentation uses the full product name.

Before you begin

You need:

• A running Decentralization Manager instance.
• A base URL such as https://decman.example.com.
• An access token issued by the configured Keycloak or Auth0 provider.
• The application role configured in DECPM_ADMIN_ROLE for admin-gated operations, when that setting is enabled.
• Canton rights and per-party credentials for operations that submit to the Ledger API.

Never use DECPM_INSECURE=true in a shared or production environment. At this reviewed commit, insecure mode accepts any inbound token and is permitted only when DECPM_CANTON_NETWORK=devnet.

Authentication

Send the access token as a bearer token:

export DECMAN_URL="<https://decman.example.com>"
export DECMAN_TOKEN="<access-token>"

curl --fail-with-body \
  -H "Authorization: Bearer ${DECMAN_TOKEN}" \
  "${DECMAN_URL}/node-config"

Authentication has two layers:

1. The server validates the caller's token against the configured identity provider.
2. Operations that call Canton use the saved per-party credentials for the target Decentralized Party.

If DECPM_ADMIN_ROLE is not set, every authenticated caller is treated as an administrator. Set an admin role in multi-user deployments.

Use the supported release reference for the complete list of admin-gated endpoints and the approved machine-to-machine token profile.

OpenAPI access

The server generates an OpenAPI document and Swagger UI from its HTTP handlers.

At the reviewed commit, these routes are mounted only in insecure mode:

• Swagger UI: /swagger-ui/
• OpenAPI JSON: /api-docs/openapi.json

A secure deployment does not expose either route. Use a versioned OpenAPI document supplied with the supported release; do not enable insecure mode to retrieve it.

Request and response conventions

• Use JSON unless an endpoint documents file upload behavior.
• Canton identifiers are strings, for example party::1220... or participant::1220....
• The HTTP server accepts payloads up to 100 MB. This limit supports DAR uploads and is not a recommended payload size for ordinary requests.
• List endpoints return arrays inside resource-specific response objects. Pagination is not documented at this commit.
• Do not assume an idempotency guarantee. The API does not document idempotency keys or client references at this commit.
• Use the instance_name returned by a workflow start request to monitor or act on that specific run.

Errors

Most handlers use the following error body:

{
  "error": "Human-readable error message"
}

The API does not yet document stable machine-readable error codes, request identifiers, field-level details, or a retryable flag. Do not parse the error text to automate a retry decision.

Before retrying a request that can change state:

1. Read the relevant resource or workflow state.
2. Confirm whether the first request created a workflow or completed an operation.
3. Use the workflow retry endpoint only for a failed workflow that is safe to repeat.
4. Escalate when the result is ambiguous.

Use the versioned API reference for endpoint-specific status codes, validation errors, conflict behavior, rate limits, and retry safety.

API families

Family	Purpose	Representative routes
Node and health	Inspect the running instance, network metadata, build, and connectivity.	/node-config, /network-info, /operator-info, /participants-status, /keys/status
Peers	Read or replace the configured Noise peer records.	GET /network-config, POST /network-config
Party configuration	Store per-party Canton credentials and Daml package references. Secrets are masked on reads.	GET /party-config/{dec_party_id}, PUT /party-config
Decentralized Parties	List shared parties and inspect topology-derived membership.	GET /decentralized-parties
Workflows	Start and monitor onboarding, membership, threshold, contract, and DAR workflows.	/onboarding, /kick, /add-party, /change-threshold, /contracts, /dars/distribute, /workflows
Invitations	Review, accept, or decline peer workflow invitations.	GET /invitations, POST /invitations/accept, POST /invitations/decline
Authentication	Inspect per-party authentication and test or grant Canton rights.	GET /auth/status, POST /auth/test, POST /auth/grant-rights
DARs and packages	Upload, distribute, compare, and inspect Daml packages.	/dars/upload, /dars/distribute, /packages, /packages/vetted
Governance	Read governance state and confirmations, then confirm, execute, expire, or cancel confirmations.	/governance/state, /governance/confirmations, /governance/confirm, /governance/execute, /governance/expire, /governance/cancel
Contracts and services	Query active contracts and module-specific service records.	/contracts/query, /services/provider, /services/user, /services/registrar

The repository also contains wallet-facing tenant DTOs under /v0/tenant/*. They are not documented as a supported integration surface here.

Workflow model

Workflow kinds

The operator API persists six workflow kinds:

• Onboarding
• Kick
• Contracts
• Dars
• AddParty
• ChangeThreshold

A run has a Coordinator or Peer role. The coordinator starts and drives the workflow. A peer accepts an invitation and performs local steps when asked.

Workflow status values

The exact serialized status values are:

Value	Meaning	Operator action
idle	No run has started for the legacy per-kind status view.	Start the workflow when prerequisites are met.
inprogress	The run is active or waiting for required peer progress.	Read current_step, peer progress, and invitations. Do not submit the same start request again.
completed	The run reached its terminal success state.	Verify the resulting Canton topology, packages, or contracts.
failed	The run stopped with an error.	Read error, correct the cause, and use the instance retry operation only when safe.
cancelled	An operator or coordinator cancelled the run.	Confirm peer state before starting a replacement run.

There are no ready, executing, or expired top-level workflow statuses at this commit. Individual current_step values provide finer progress. Governance confirmation expiry is separate from workflow status.

Start response

A successful workflow start returns:

{
  "status": "inprogress",
  "message": "<human-readable message>",
  "instance_name": "<workflow-instance>"
}

Store instance_name. Concurrent runs of the same kind are supported, so the legacy per-kind status and cancel routes can be ambiguous.

Persisted run fields

GET /workflows returns a runs array. Each run includes:

• instance_name, kind, role, and status.
• current_step, step_index, and step_total.
• expected_peers and completed_peers.
• error when the run failed or was cancelled with a reason.
• Context fields such as dec_party_id, prefix, participants, thresholds, package names, or DAR filenames when relevant.
• created_at and updated_at as Unix timestamps.

The API also returns config_json, which is an internal serialized copy of the start configuration used for recovery. Do not build client behavior around its undocumented contents.

General workflow sequence

1. Validate peer records, authentication, Canton access, and workflow-specific inputs.
2. Send the workflow start request to the coordinator.
3. Store the returned instance_name.
4. Other participants read and accept their invitations.
5. Poll GET /workflows and match the run by instance_name.
6. Wait for completed, failed, or cancelled.
7. Verify the resulting Canton state or deployed artifact.

The server persists workflow progress in SQLite. On restart, it attempts to resume runs that were inprogress. Recovery has workflow-specific limits. Review the operations and troubleshooting guides before relying on restart recovery.

Example: start and monitor onboarding

Create a Decentralized Party with selected peers and an explicit topology threshold:

curl --fail-with-body \
  -X POST "${DECMAN_URL}/onboarding" \
  -H "Authorization: Bearer ${DECMAN_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "party_id_prefix": "example-party",
    "peer_ids": [
      "participant-2::1220...",
      "participant-3::1220..."
    ],
    "threshold": 2
  }'

Example response:

{
  "status": "inprogress",
  "message": "Onboarding workflow started",
  "instance_name": "Onboarding-<unique-value>"
}

Poll the workflow collection and select the returned instance:

curl --fail-with-body \
  -H "Authorization: Bearer ${DECMAN_TOKEN}" \
  "${DECMAN_URL}/workflows"

Do not treat the example message or instance_name format as stable. Only the documented fields and exact enum values should drive client logic.

Workflow control

Instance-scoped workflow control is the least ambiguous method:

• Cancel an active run: POST /workflows/{instance_name}/cancel
• Retry a failed run: POST /workflows/{instance_name}/retry
• Dismiss a visible terminal run: POST /workflows/{instance_name}/dismiss

Legacy per-kind status and cancel endpoints also exist for onboarding, contracts, kick, add-party, change-threshold, and DAR distribution. Prefer the instance-scoped routes for new integrations.

Before cancel or retry, read the latest run state. A coordinator action can also affect accepted peer-side runs and pending invitations.

Check the versioned API reference for eligibility rules and conflict status codes. Never assume a workflow step is safe to repeat after a partial Canton submission.

Invitations

Read pending invitations:

curl --fail-with-body \
  -H "Authorization: Bearer ${DECMAN_TOKEN}" \
  "${DECMAN_URL}/invitations"

Accept an invitation by its id:

curl --fail-with-body \
  -X POST "${DECMAN_URL}/invitations/accept" \
  -H "Authorization: Bearer ${DECMAN_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"id":"<invitation-id>"}'

A peer can decline the same invitation through /invitations/decline. A decline fails the matching coordinator run when the invitation carries the coordinator's workflow instance.

Client implementation checklist

• Pin the documentation and OpenAPI definition to a supported release.
• Use bearer authentication and least-privilege roles.
• Store workflow instance_name values.
• Match exact enum values instead of human-readable messages.
• Read state before retrying a write.
• Use bounded polling with backoff and a client-side deadline.
• Redact tokens, client secrets, party credentials, and contract payloads from logs.
• Verify the Canton result after a completed workflow.
• Test restart, cancellation, peer unavailability, and partial-progress behavior.

Troubleshooting

Symptom	Likely cause	Next action
401 or token validation failure	Missing token, untrusted issuer, invalid audience, expired token, or identity-provider discovery failure.	Check the configured Keycloak or Auth0 issuer, audience, JWKS access, and token expiry.
403 on a sensitive route	The access token lacks the role configured by DECPM_ADMIN_ROLE.	Request the configured application role. Do not disable the role gate as a workaround.
A workflow remains inprogress	A peer has not accepted, connected, or completed the current step.	Read current_step, expected_peers, completed_peers, /invitations, and /participants-status.
A retry may duplicate work	The client lost the first response or the workflow failed after a partial Canton operation.	Read /workflows and verify Canton state before retrying. Escalate if the result remains ambiguous.
Swagger UI is missing	The server is running in secure mode.	Do not enable insecure mode in production. Use the versioned OpenAPI artifact supplied with the supported release.

Technical sources

• Repository README at the reviewed commit
• Architecture reference at the reviewed commit
• Shared HTTP DTOs at the reviewed commit
• Shared workflow types at the reviewed commit
• HTTP server and workflow recovery at the reviewed commit
• Workflow state persistence at the reviewed commit

Related pages

• Decentralization Manager authentication and operator roles
• Decentralization Manager package and contract operations
• Decentralization Manager membership and governance changes
• Decentralization Manager backup, recovery, and mesh upgrades
• Decentralization Manager compatibility, releases, and troubleshooting
• Decentralization Manager security architecture

Next step

👉 Secure API access: Decentralization Manager authentication and operator roles.