Organization deployment API

Organization deployment creates the organization context and starts the setup workflow. The workflow prepares the platform system, registries, roles, identity, compliance, factories, add-ons, feeds, and paymaster nodes. Onboarding automation uses this API path before asset creation, post-deployment role assignment, or provider-specific configuration.

For the broader setup sequence, see Platform setup overview. For API authentication and OpenAPI discovery, see API reference.

Prerequisites

Before calling the deployment API, confirm these inputs and runtime conditions:

• The caller has an authenticated session for the user that owns the new organization setup.
• The organization name is final enough for operators to identify the workspace.
• Currency choices use ISO 4217 alpha-3 codes such as EUR, USD, or SGD.
• targetCurrencies includes baseCurrency, contains no duplicates, and includes at least one currency other than baseCurrency.

Quickstart

Start deployment with POST /api/v2/organizations/deploy. The response returns a deploymentId and the current deployment tree.

curl -X POST "$DALP_API_URL/api/v2/organizations/deploy" \
  -H "Content-Type: application/json" \
  -b "$DALP_SESSION_COOKIE" \
  -c /tmp/dalp-org-deploy.cookies \
  -d '{
    "name": "Northwind Treasury",
    "baseCurrency": "EUR",
    "targetCurrencies": ["EUR", "SGD"]
  }'

{
  "deploymentId": "org_01hz8y2w6q8x7n4p9r3s2t1v0w",
  "tree": [
    { "id": "wallet", "label": "Wallet", "type": "wallet", "status": "pending" },
    {
      "id": "organization",
      "label": "Organization",
      "type": "system",
      "status": "pending",
      "children": [
        { "id": "system", "label": "System Contract", "type": "system", "status": "pending" },
        { "id": "registries", "label": "Registries", "type": "registry", "status": "pending" },
        { "id": "roles", "label": "Access Roles", "type": "role", "status": "pending" },
        { "id": "identity", "label": "Identity", "type": "identity", "status": "pending" },
        { "id": "compliance", "label": "Compliance Modules", "type": "compliance", "status": "pending" },
        { "id": "factories", "label": "Asset Factories", "type": "factory", "status": "pending" },
        { "id": "addons", "label": "Addon Factories", "type": "addon", "status": "pending" }
      ]
    },
    {
      "id": "smart-wallet",
      "label": "Provisioning Smart Wallet",
      "type": "wallet",
      "status": "pending"
    }
  ]
}

The exact node labels can vary by deployment state. The feeds and paymaster nodes appear only when the active chain supports those setup phases. Integration code should key off id, type, and status instead of display text.

Request fields

DALP rejects the request before deployment starts when the currency set is invalid. Fix the request body before retrying.

Monitor deployment progress

Open the deployment stream after the create response returns a deploymentId. Reuse the cookie jar from the create request so the active-organization cookie set during deployment is preserved for the server-sent event stream.

curl -N "$DALP_API_URL/api/v2/organizations/deploy/org_01hz8y2w6q8x7n4p9r3s2t1v0w/stream" \
  -H "Accept: text/event-stream" \
  -b /tmp/dalp-org-deploy.cookies

The stream emits deployment events as server-sent events.

Deployment node status is one of pending, in-progress, completed, or failed. A complete event is terminal for that stream. Reconnect only when the terminal error is retryable or when the operator restarts deployment.

Organization deployment and system creation scope

Organization deployment is the public setup entry point for onboarding automation. It starts a workflow that includes system creation and the remaining organization bootstrap steps.

The lower-level system creation route deploys a SMART system with identity registry, compliance engine, and token factory registry contracts. New integrations should not call it as a substitute for organization deployment. Organization deployment establishes the workspace scope, then continues through system, registry, role, identity, compliance, factory, feed, add-on, and paymaster setup.

System create requests accept an optional contract address. When omitted, the server resolves the standard system factory address from indexed directory state. Successful system creation returns a systemAddress; clients can read that system after the operation completes.

For new onboarding work, route clients to organization deployment instead of legacy system creation. Keep system creation for existing system-level integrations that already own their organization context and need to deploy or resume only the SMART system layer.

Retry and idempotency rules

Organization deployment is a workflow. If a deployment is interrupted after a child node completes, retrying deployment for the same organization can resume from completed phases instead of redeploying every phase. The tested retry path covers system, registries, roles, identity, compliance, factories, add-ons, feeds, and paymaster phases.

Client code should follow this rule:

1. Start deployment once for the organization.
2. Store the returned deploymentId with the onboarding session.
3. Subscribe to the deployment stream until complete or error.
4. On interruption, look up the active deployment before starting a new deployment.
5. Treat completed nodes as durable progress and failed nodes as operator-visible work.

Do not create assets until organization deployment completes successfully and the active organization context is set for the caller.

Related pages

• Platform setup overview maps the full setup path before asset creation.
• DALP admin operating model explains organization, user, role, API key, webhook, provider, and operator-wallet responsibilities.
• API reference explains OpenAPI discovery, authentication, headers, and route namespaces.
• Organization and system scope explains how integrations stay in the correct organization and system context.
• Create an asset starts the first asset workflow after platform setup is complete.