Provision Service API

Manage Canton Network parties and Daml 3.x application deployment on Canton 3.4. The Provision Service handles party allocation across Canton networks (DevNet, TestNet, MainNet) and the full lifecycle of Daml application registration, access control, and deployment through the Tenzro Platform validators.

Network Access Workflow

DevNet — Auto-approved. Allocations become active immediately upon creation. No admin approval required. Participant: json.devnet.tenzro.network
TestNet — Auto-approved. Same as DevNet. Participant: json.testnet.tenzro.network
MainNet — Requires explicit Tenzro admin approval. Allocations start as pending and must be approved via the console or the PUT /api/provision/apps/:id/access endpoint before deployment. Participant: json.mainnet.tenzro.network

Authentication

All endpoints require both headers. The health check endpoint (GET /api/provision/health) is public and does not require authentication.

X-API-Key: tnz_{tenant}_{secret}
X-Tenant-Id: your-tenant-id

API keys follow the format tnz_{tenant}_{secret}. Do not use Authorization: Bearer tokens for this service.

Endpoints

Method	Endpoint	Description	Auth
`GET`	`/api/provision/parties`	List all parties for tenant	Required
`POST`	`/api/provision/parties`	Allocate a new Canton party	Required
`DELETE`	`/api/provision/parties/:party_id`	Delete a party	Required
`GET`	`/api/provision/apps`	List all apps for tenant	Required
`POST`	`/api/provision/apps`	Create a new app	Required
`GET`	`/api/provision/apps/:app_id`	Get app details	Required
`DELETE`	`/api/provision/apps/:app_id`	Delete an app	Required
`PUT`	`/api/provision/apps/:app_id/access`	Update network access status	Required
`POST`	`/api/provision/apps/:app_id/deploy`	Deploy app to Canton network	Required
`POST`	`/api/provision/apps/:app_id/undeploy`	Undeploy app from network	Required
`GET`	`/api/provision/health`	Health check	None

Party Types

Party types classify the role of a Canton identity. Pass the integer value in the party_type field when allocating a party.

Value	Name	Description
`1`	Tenant	Root tenant party
`2`	Organization	Sub-tenant organization or department identity
`3`	User	End-user identity on the ledger
`4`	Wallet	Wallet or treasury party
`5`	Service	Backend service account identity
`6`	Application	Daml application party

Networks

The network field in party and deployment requests accepts an integer. String values ("devnet", "mainnet") are used in app access and deployment request bodies.

Integer value	String value	Description
`1`	`devnet`	Development network for testing
`2`	`testnet`	Pre-production test network
`3`	`mainnet`	Production Canton Network

Party Management

List Parties

GET /api/provision/parties
X-API-Key: tnz_tenant_secret
X-Tenant-Id: tenant_abc123

Query Parameters

Parameter	Type	Description
`network`	integer	Filter by network (1=Devnet, 2=Testnet, 3=Mainnet)
`page_size`	integer	Number of results per page
`page_token`	string	Pagination cursor from a previous response

Response

{
  "parties": [
    {
      "party_id": "alice::122057a8...::1",
      "display_name": "Alice User",
      "party_type": "user",
      "network": "devnet",
      "participant_id": "participant::devnet::67890",
      "created_at": 1705312200
    },
    {
      "party_id": "acme-wallet::122057b9...::1",
      "display_name": "Acme Treasury Wallet",
      "party_type": "wallet",
      "network": "devnet",
      "participant_id": "participant::devnet::67890",
      "created_at": 1705314000
    }
  ],
  "next_page_token": "eyJvZmZzZXQiOjJ9",
  "total_count": 2
}

Allocate Party

Allocates a new Canton party on the specified network. The Canton participant generates a cryptographic identity and returns the full party ID, which includes a fingerprint of the participant's public key.

POST /api/provision/parties
X-API-Key: tnz_tenant_secret
X-Tenant-Id: tenant_abc123
Content-Type: application/json

{
  "tenant_id": "tenant_abc123",
  "display_name": "Alice User",
  "party_type": 3,
  "network": 1,
  "party_id_hint": "alice",
  "use_external_keys": false
}

Request Fields

Field	Type	Required	Description
`tenant_id`	string	Yes	Tenant that owns this party
`display_name`	string	Yes	Human-readable name for the party
`party_type`	integer	No	Party type (1–6, see Party Types table)
`network`	integer	No	Target network (1=Devnet, 2=Testnet, 3=Mainnet)
`party_id_hint`	string	No	Suggested name component for the generated party ID. The participant appends a cryptographic fingerprint to this hint.
`use_external_keys`	boolean	No	Whether to use externally managed signing keys

Response

{
  "success": true,
  "party_id": "alice::122057a8...::1",
  "display_name": "Alice User",
  "participant_id": "participant::devnet::67890"
}

Error Response

{
  "success": false,
  "error": "Party allocation failed: participant not available on requested network"
}

Delete Party

DELETE /api/provision/parties/alice::122057a8...::1
X-API-Key: tnz_tenant_secret
X-Tenant-Id: tenant_abc123

Response

{
  "success": true,
  "message": "Party deleted"
}

App Management

An app represents a Daml application registered with the platform. Each app tracks its access status and deployment status independently for Devnet and Mainnet. After creating an app, you must request and receive network access approval before deploying.

List Apps

GET /api/provision/apps
X-API-Key: tnz_tenant_secret
X-Tenant-Id: tenant_abc123

Response

{
  "apps": [
    {
      "id": "app_xyz789",
      "name": "acme-trade-finance",
      "description": "Daml-based trade finance application",
      "tenant_id": "tenant_abc123",
      "deployment_type": "daml",
      "repository": "https://github.com/acme/trade-finance",
      "endpoint": "https://api.acme.com/trade",
      "created_at": 1704880800,
      "devnet_access_status": "approved",
      "devnet_deployment_status": "deployed",
      "devnet_party_id": "acme-trade-finance::122057c1...::1",
      "devnet_ledger_api_url": "https://json.devnet.tenzro.network",
      "devnet_json_api_url": "https://json.devnet.tenzro.network",
      "devnet_deployed_at": 1705054800,
      "mainnet_access_status": "pending",
      "mainnet_deployment_status": null,
      "mainnet_party_id": null,
      "mainnet_ledger_api_url": null,
      "mainnet_json_api_url": null,
      "mainnet_deployed_at": null
    }
  ]
}

Create App

POST /api/provision/apps
X-API-Key: tnz_tenant_secret
X-Tenant-Id: tenant_abc123
Content-Type: application/json

{
  "name": "acme-trade-finance",
  "description": "Daml-based trade finance application",
  "tenant_id": "tenant_abc123",
  "deployment_type": "daml",
  "repository": "https://github.com/acme/trade-finance",
  "endpoint": "https://api.acme.com/trade"
}

Request Fields

Field	Type	Required	Description
`name`	string	Yes	Identifier name for the application
`tenant_id`	string	Yes	Tenant that owns this application
`description`	string	No	Human-readable description
`deployment_type`	string	No	Deployment type. Defaults to `custom`. Use `daml` for Daml smart contract applications.
`repository`	string	No	Source repository URL
`endpoint`	string	No	Application's public endpoint URL

Response

Returns the full App object. Access statuses default to pending and deployment statuses are null until the app is deployed.

{
  "id": "app_xyz789",
  "name": "acme-trade-finance",
  "description": "Daml-based trade finance application",
  "tenant_id": "tenant_abc123",
  "deployment_type": "daml",
  "repository": "https://github.com/acme/trade-finance",
  "endpoint": "https://api.acme.com/trade",
  "created_at": 1704880800,
  "devnet_access_status": "pending",
  "devnet_deployment_status": null,
  "mainnet_access_status": "pending",
  "mainnet_deployment_status": null
}

Get App

GET /api/provision/apps/app_xyz789
X-API-Key: tnz_tenant_secret
X-Tenant-Id: tenant_abc123

Response

Returns the full App object (see App Object Reference).

{
  "id": "app_xyz789",
  "name": "acme-trade-finance",
  "description": "Daml-based trade finance application",
  "tenant_id": "tenant_abc123",
  "deployment_type": "daml",
  "repository": "https://github.com/acme/trade-finance",
  "endpoint": "https://api.acme.com/trade",
  "created_at": 1704880800,
  "devnet_access_status": "approved",
  "devnet_deployment_status": "deployed",
  "devnet_party_id": "acme-trade-finance::122057c1...::1",
  "devnet_ledger_api_url": "https://json.devnet.tenzro.network",
  "devnet_json_api_url": "https://json.devnet.tenzro.network",
  "devnet_deployed_at": 1705054800,
  "mainnet_access_status": "pending",
  "mainnet_deployment_status": null,
  "mainnet_party_id": null,
  "mainnet_ledger_api_url": null,
  "mainnet_json_api_url": null,
  "mainnet_deployed_at": null
}

Delete App

DELETE /api/provision/apps/app_xyz789
X-API-Key: tnz_tenant_secret
X-Tenant-Id: tenant_abc123

Response

{
  "success": true,
  "message": "App deleted"
}

App Access Control

Update Network Access Status

Applications must be granted access to a network before they can be deployed. Use this endpoint to set the access status for a specific network. Typically called by an administrator after reviewing the application. Returns the updated App object.

PUT /api/provision/apps/app_xyz789/access
X-API-Key: tnz_tenant_secret
X-Tenant-Id: tenant_abc123
Content-Type: application/json

{
  "network": "devnet",
  "status": "approved"
}

Request Fields

Field	Type	Required	Description
`network`	string	Yes	Network to update: `devnet` or `mainnet`
`status`	string	Yes	New access status: `pending`, `approved`, or `denied`

Response

Returns the full updated App object with the new access status reflected.

{
  "id": "app_xyz789",
  "name": "acme-trade-finance",
  "tenant_id": "tenant_abc123",
  "devnet_access_status": "approved",
  "devnet_deployment_status": null,
  ...
}

App Deployment

Deploy App

Deploy an application to a Canton network. The app must have approved access status for the target network before deployment. On success, the response includes the allocated Canton party ID and the Ledger API and JSON API URLs for the deployed app.

POST /api/provision/apps/app_xyz789/deploy
X-API-Key: tnz_tenant_secret
X-Tenant-Id: tenant_abc123
Content-Type: application/json

{
  "network": "devnet"
}

Request Fields

Field	Type	Required	Description
`network`	string	Yes	Target network: `devnet` or `mainnet`

Response

{
  "success": true,
  "message": "Application deployed successfully",
  "deployment": {
    "network": "devnet",
    "status": "deployed",
    "party_id": "acme-trade-finance::122057c1...::1",
    "ledger_api_url": "https://json.devnet.tenzro.network",
    "json_api_url": "https://json.devnet.tenzro.network",
    "deployed_at": "2024-01-12T14:00:00Z"
  }
}

Undeploy App

Remove an application's deployment from a Canton network. The app record and its access status are retained; only the active deployment is torn down. The network-specific party ID, Ledger API URL, and JSON API URL fields on the app will be cleared.

POST /api/provision/apps/app_xyz789/undeploy
X-API-Key: tnz_tenant_secret
X-Tenant-Id: tenant_abc123
Content-Type: application/json

{
  "network": "devnet"
}

Response

{
  "success": true,
  "message": "Application undeployed successfully"
}

Health Check

This endpoint is public and does not require authentication headers.

GET /api/provision/health

Response

{
  "status": "ok",
  "service": "provision",
  "version": "1.0.0"
}

App Object Reference

The full App object returned by app endpoints. Timestamp fields (created_at, *_deployed_at) are Unix epoch integers. Network-specific fields are null until the app has been deployed to that network.

Field	Type	Description
`id`	string	Unique application identifier
`name`	string	Application name
`description`	string \| null	Optional description
`tenant_id`	string \| null	Owning tenant
`deployment_type`	string \| null	Deployment type (e.g. `daml`, `custom`)
`repository`	string \| null	Source repository URL
`endpoint`	string \| null	Application endpoint URL
`created_at`	integer \| null	Unix timestamp of creation
`devnet_access_status`	string \| null	Devnet access status: `pending`, `approved`, or `denied`
`devnet_deployment_status`	string \| null	Devnet deployment status: `deployed` or `undeployed`
`devnet_party_id`	string \| null	Canton party ID allocated for this app on Devnet
`devnet_ledger_api_url`	string \| null	gRPC Ledger API URL on Devnet
`devnet_json_api_url`	string \| null	HTTP JSON API URL on Devnet
`devnet_deployed_at`	integer \| null	Unix timestamp of last Devnet deployment
`mainnet_access_status`	string \| null	Mainnet access status: `pending`, `approved`, or `denied`
`mainnet_deployment_status`	string \| null	Mainnet deployment status: `deployed` or `undeployed`
`mainnet_party_id`	string \| null	Canton party ID allocated for this app on Mainnet
`mainnet_ledger_api_url`	string \| null	gRPC Ledger API URL on Mainnet
`mainnet_json_api_url`	string \| null	HTTP JSON API URL on Mainnet
`mainnet_deployed_at`	integer \| null	Unix timestamp of last Mainnet deployment

Canton Network Integration

The Provision Service manages identities and applications on Canton Network (Canton 3.4, Daml 3.x), a privacy-first enterprise blockchain built on the Global Synchronizer. The Tenzro Platform operates Canton participant nodes on each network. Key concepts:

Parties - Cryptographic identities on the Canton ledger that own and observe Daml contracts. A party ID is generated by the hosting participant and incorporates the participant's public key fingerprint.
Participant - The Canton node that hosts parties and connects them to synchronization domains. Tenzro operates participants at json.devnet.tenzro.network, json.testnet.tenzro.network, and json.mainnet.tenzro.network.
Daml 3.x Apps - Applications defined using Daml 3.x smart contracts (Canton Ledger API v2), deployed per-network with a dedicated Canton party ID. Each deployment provides JSON Ledger API connection details.
JSON Ledger API v2 - HTTP/JSON interface for Daml command submission, contract queries, and transaction streams. Canton 3.4+ uses the unified JSON Ledger API (port 7575) which replaces the separate gRPC and JSON APIs from earlier versions.
Access workflow - DevNet and TestNet access is auto-approved: allocations become active immediately. MainNet access requires explicit Tenzro admin approval via the PUT /access endpoint before the app can be deployed.