Create a tenant

This quickstart is for system administrators who need to create a tenant in Workspace. When you finish, Workspace has provisioned the tenant and you can explicitly switch to it to continue the business setup.

Use this flow only in the System Tenant. Check the active context in the app footer before you create anything. If you first need to distinguish tenants, memberships, and the System view, read Tenants, user accounts, and the System view.

Prerequisites

Your user account needs:

  • access to the System Tenant,
  • the tenants:list scope for the System > Tenants page,
  • the tenants:create scope for the create action, and
  • either tenants:read or system_diagnostics:read so Workspace can display the provisioning status.

The page requires tenants:list. The create dialog is available only in the System Tenant and only with tenants:create. If the action is missing despite the expected scopes, first check the active tenant in the footer.

Create the tenant

  1. Switch to the System Tenant.
  2. Open System > Tenants.
  3. Select Create.
  4. Enter a name.
  5. Optionally enter a slug. Leave the field empty if Workspace should derive it from the name.
  6. Submit the operation once.

Workspace accepts the operation and shows its progress in the open dialog. Repeated transmission attempts for the same operation do not create a second tenant. Keep the dialog open while you want to monitor the running status.

Create a tenant with nucli

Use this flow for scripts or traceable command-line administration. The system profile must target the System Tenant. Check the context and scopes first:

bash
nucli --tenant system whoami --scopes
nucli --tenant system system tenants list --json

Choose an idempotency key for each new create operation. Reuse the same key only when you need to replay that exact operation after an uncertain transport failure:

bash
nucli --tenant system system tenants create "Example Ltd" \
  --slug example \
  --idempotency-key <unique-key> \
  --wait \
  --json

Omit --slug when Workspace should derive the slug from the name. --wait follows the provisioning status published by the server. The command does not guess an API path and stops when discovery, the System Tenant context, or the effective scopes do not match the contract.

Read an existing tenant and its status separately when needed:

bash
nucli --tenant system system tenants get <tenant-id> --json
nucli --tenant system system tenant-provisioning status <tenant-id> --json

The CLI flow has succeeded when the create command reports succeeded and list or get confirms the tenant. nucli does not switch the active tenant afterwards.

Control creation with an MCP agent

Start nucli mcp serve with the System Tenant profile. The agent first uses nucleus_system_tenant_create_plan to create a read-only plan. Check its name, optional slug, and idempotency key. Approve only that exact plan.

Only then may the agent call nucleus_system_tenant_create with the unchanged values and approved: true. It monitors provisioning through nucleus_system_tenant_provisioning_status and confirms the result through nucleus_system_tenants_list and nucleus_system_tenant_read. Without explicit approval or an idempotency key, the mutating tool sends no create request.

Load the embedded agent workflow with:

bash
nucli skills show tenant-administration

The skill identifies its binary-bound contract as tenant-administration/v1. Agents must not construct API paths or fall back to direct database access or numin.

Understand the provisioning status

Creation is complete only when the status reaches succeeded. The other statuses mean:

StatusMeaningNext action
pendingThe operation is waiting to run.Wait for the next status update.
runningWorkspace is setting up the product modules.Keep the dialog open.
retry_waitWorkspace is waiting before a controlled retry.Wait; do not start the same operation in parallel.
blockedA prerequisite prevents completion.Review the safe guidance and resolve the stated prerequisite.
failedProvisioning could not finish.Review the safe error guidance and contact operations if needed.
succeededAll intended provisioning steps have completed.Use the offered action if you want to switch to the new tenant.

Workspace does not offer a tenant switch for blocked, failed, or an unknown status. This prevents you from entering a partially configured tenant by mistake.

If a blocked run reports the safe error code tenant_provisioning_target_drift, its intended provisioning target changed after the run started. Workspace executes no further steps under that old run and does not rewrite its target. Do not treat resubmitting the original create operation or reusing its idempotency key as a retry.

Recovery requires an authorized administrator to start a new, explicit initialization or provisioning run with the current target. Use only the administration action published by the installed version. If that action is not available, contact operations instead of guessing an API path or changing the blocked run.

Verify the result

Creation succeeded when:

  • the dialog reports succeeded,
  • the tenant-switch action is available, and
  • the new entry appears under System > Tenants.

Workspace never switches tenants automatically. Select the offered action only when you are ready to continue in the new tenant. After the switch, verify the active tenant in the app footer again.

Provisioning sets up the standard product foundation. It does not replace the business configuration required for go-live.

The managed workflow library is part of this product foundation. For a new business tenant, Workspace creates the required selection when no explicit selection exists. Provisioning succeeds only after Workspace can resolve and compile the managed standard workflows unambiguously. Workspace neither activates a global workflow definition nor creates a tenant-local copy for this purpose.

Next steps