Install governance
What tenants experience when they install your app — and the contract your app lives under.
The install flow
| gate | behaviour |
|---|---|
| 1 · Permission review | The tenant sees every scope from your manifest and must acknowledge all of them. Missing acknowledgements → 428 PERMISSIONS_NOT_ACKNOWLEDGED. |
| 2 · Sandbox first | Apps that provision resources must be sandbox-installed before a prod install is allowed (428 SANDBOX_FIRST). Sandbox installs prefix custom objects with sbx_ and land workflows as drafts. |
| 3 · Atomic provision | The engine provisions in order (objects → fields → workflows → webhooks → agents). Any failure rolls back everything created so far — no half-installed apps, ever. |
| 4 · Acting as the installer | Provisioning runs with the installing user's identity — their RBAC role and plan limits apply. An install can fail on a plan gate (e.g. the tenant's custom-object limit); that surfaces in the rollback report. |
One-click uninstall
The platform records every resource your install created — { kind, id, name } for custom objects, workflows, webhook subscriptions and agents — and deletes them all on uninstall (newest-first). Partial failures are reported per resource; nothing is silently stranded.
POST /api/marketplace/installs/{installId}/uninstall
# → { "uninstalled": true, "complete": true, "cleanup": [ { kind, name, deleted } … ] }Design for this contract
- Everything you provision must be safe to delete — keep upstream state (your SaaS) authoritative, treat platform mirrors as rebuildable.
- Idempotent syncs: a tenant may uninstall and reinstall; your connector must converge, not duplicate.
- Name resources clearly (your app name shows in the tenant's workflow list and schema builder).