Workspace Provisioning

The four-step provisioning saga that creates workspaces, environments, and Dataplane tenants.

Creating a workspace triggers an asynchronous provisioning saga. The API returns 202 Accepted immediately with a provisioning_run_id; background tasks complete physical setup.

API entry point

POST /v1/workspaces
Authorization: Bearer <token>
Content-Type: application/json

{
  "account_id": "<uuid>",
  "name": "Production",
  "slug": "production",
  "tenancy_model": "direct"
}

Response:

{
  "workspace_id": "<uuid>",
  "provisioning_run_id": "<uuid>"
}

Requires administer on the parent account.

Saga steps

Step	What happens	Status after
1 — Logical	Workspace row, owner membership, default environments (`dev`, `staging`, `prod`), SpiceDB tuples	`step_1_done`
2 — Physical	Register Dataplane tenant via Admin SDK; store `dataplane_tenant_id` in workspace settings	`step_2_done`
3 — Quota	Allocate plan-tier quota ceilings (stubbed for some tiers)	`step_3_done`
4 — Complete	Mark run succeeded; emit `client.provisioned` event	`succeeded`

Step 1 runs in a single Postgres transaction. SpiceDB writes use the DLQ pattern if gRPC fails after commit.

Default environments

Every new workspace gets three environments:

dev
staging
prod

Environment promotion (moving releases between them) is a separate pillar — not yet available in the Customer Portal.

Failure handling

Failed runs are marked in provisioning_runs with error details
A background reconciler retries stale runs
Workspace row may exist even if later steps fail — check run status before assuming Dataplane is ready

Customer Portal

Admins create workspaces from Workspaces. The list shows status; detail page exposes the workspace UUID needed for API and Shell registration.

Event emission — client.provisioned
Workspaces API — CRUD endpoints
Dataplane authz brief — tenant boundary