> For the complete documentation index, see [llms.txt](https://docs.bitsafe.finance/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.bitsafe.finance/decentralization-manager/operations-and-reference/api-and-workflow-reference.md). # 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](/decentralization-manager/concepts-and-development/architecture-overview.md). Product-wide troubleshooting and compatibility belong in [Decentralization Manager compatibility, releases, and troubleshooting](/decentralization-manager/operations-and-reference/compatibility-releases-and-troubleshooting.md). 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. {% hint style="info" %} 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`. {% endhint %} ### Authentication Send the access token as a bearer token: ```bash export DECMAN_URL="" export DECMAN_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: ```json { "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: ```json { "status": "inprogress", "message": "", "instance_name": "" } ``` 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: ```bash 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: ```json { "status": "inprogress", "message": "Onboarding workflow started", "instance_name": "Onboarding-" } ``` Poll the workflow collection and select the returned instance: ```bash 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: ```bash curl --fail-with-body \ -H "Authorization: Bearer ${DECMAN_TOKEN}" \ "${DECMAN_URL}/invitations" ``` Accept an invitation by its `id`: ```bash curl --fail-with-body \ -X POST "${DECMAN_URL}/invitations/accept" \ -H "Authorization: Bearer ${DECMAN_TOKEN}" \ -H "Content-Type: application/json" \ -d '{"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](https://github.com/DLC-link/decentralization-manager/blob/76d7156c85e605abc008e5fadf8aaa97f4706471/README.md) * [Architecture reference at the reviewed commit](https://github.com/DLC-link/decentralization-manager/blob/76d7156c85e605abc008e5fadf8aaa97f4706471/docs/ARCHITECTURE.md) * [Shared HTTP DTOs at the reviewed commit](https://github.com/DLC-link/decentralization-manager/blob/76d7156c85e605abc008e5fadf8aaa97f4706471/crates/common/src/api.rs) * [Shared workflow types at the reviewed commit](https://github.com/DLC-link/decentralization-manager/blob/76d7156c85e605abc008e5fadf8aaa97f4706471/crates/common/src/types.rs) * [HTTP server and workflow recovery at the reviewed commit](https://github.com/DLC-link/decentralization-manager/blob/76d7156c85e605abc008e5fadf8aaa97f4706471/crates/decman/src/server/mod.rs) * [Workflow state persistence at the reviewed commit](https://github.com/DLC-link/decentralization-manager/blob/76d7156c85e605abc008e5fadf8aaa97f4706471/crates/decman/src/workflow/state.rs) ### Related pages * [Decentralization Manager authentication and operator roles](/decentralization-manager/operations-and-reference/authentication-and-operator-roles.md) * [Decentralization Manager package and contract operations](/decentralization-manager/operations-and-reference/package-and-contract-operations.md) * [Decentralization Manager membership and governance changes](/decentralization-manager/operations-and-reference/membership-and-governance-changes.md) * [Decentralization Manager backup, recovery, and mesh upgrades](/decentralization-manager/operations-and-reference/backup-recovery-and-upgrades.md) * [Decentralization Manager compatibility, releases, and troubleshooting](/decentralization-manager/operations-and-reference/compatibility-releases-and-troubleshooting.md) * [Decentralization Manager security architecture](/decentralization-manager/operations-and-reference/security-architecture.md) ### Next step 👉 **Secure API access:** [Decentralization Manager authentication and operator roles](/decentralization-manager/operations-and-reference/authentication-and-operator-roles.md). --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.bitsafe.finance/decentralization-manager/operations-and-reference/api-and-workflow-reference.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.