Create workspace

Outcome

Create one canonical workspace for an application and organization.

Before you start

• Verify the credential with topolo whoami --json and inspect the exact published action. Stop on runtime authorization denial; do not widen permissions or switch contexts automatically.

• Discover the target application and use the organization carried by the credential. A request organizationId is not a context override.

• Use workspaces.list for the same target application and organization. Inspect policy.canCreate and reason; ownership, application access and permission to create additional workspaces are distinct.

• Validate and plan the exact request before execution. --confirm is a transport guard; the intended change must already be authorized.

Discover the target

topolo actions get app_topolo_auth.workspaces.create --detail --json
topolo apps --json
topolo whoami --json
topolo workspaces list topolo-docs --json

Input fields

Effects

• Creates canonical workspace identity, ownership and default state after target-application permission and creation-policy checks. Does not create application content.

Interpret the response

data.workspace is the new canonical record. Preserve its stable id and slug independently of the display name. Creation can fail on organization or per-user limits even when the application is accessible.

Worked examples

These are raw target-handler responses, not gateway or CLI envelopes. They were captured in a local test with simulated dependencies. Fixture identifiers and credentials are illustrative and cannot authorize a live call. Discover your own organization, application, workspace and key ids. Local CLI/stdio MCP may replace credential strings with protected references; preserve the reference and do not extract the underlying secret.

Minimal example

Input · payload.json:

{
  "organizationId": "org_fixture",
  "appId": "app_topolo_docs",
  "name": "minimal integration reference"
}

CLI:

topolo actions validate app_topolo_auth.workspaces.create --data @payload.json --json
topolo actions plan app_topolo_auth.workspaces.create --data @payload.json --json
topolo actions call app_topolo_auth.workspaces.create --data @payload.json --confirm --json

MCP:

{
  "tool": "topolo_call_action",
  "arguments": {
    "actionId": "app_topolo_auth.workspaces.create",
    "input": {
      "organizationId": "org_fixture",
      "appId": "app_topolo_docs",
      "name": "minimal integration reference"
    },
    "confirm": true
  }
}

Captured local handler response · HTTP 201:

{
  "success": true,
  "message": "Workspace created",
  "data": {
    "workspace": {
      "id": "ws_created_minimal",
      "appId": "app_topolo_docs",
      "organizationId": "org_fixture",
      "name": "minimal integration reference",
      "avatar": {
        "kind": "preset",
        "presetId": "orbit"
      },
      "slug": "ws_created_minimal",
      "status": "active",
      "isDefault": false,
      "ownerUserId": "usr_fixture",
      "createdByUserId": "usr_fixture",
      "createdAt": 1,
      "updatedAt": 1,
      "archivedAt": null
    }
  },
  "timestamp": "2026-10-02T14:48:16.381Z"
}

data.workspace is the new canonical record. Preserve its stable id and slug independently of the display name. Creation can fail on organization or per-user limits even when the application is accessible.

Workflow example

Input · payload.json:

{
  "organizationId": "org_fixture",
  "appId": "app_topolo_docs",
  "name": "workflow integration reference",
  "isDefault": true
}

CLI:

topolo actions validate app_topolo_auth.workspaces.create --data @payload.json --json
topolo actions plan app_topolo_auth.workspaces.create --data @payload.json --json
topolo actions call app_topolo_auth.workspaces.create --data @payload.json --confirm --json

MCP:

{
  "tool": "topolo_call_action",
  "arguments": {
    "actionId": "app_topolo_auth.workspaces.create",
    "input": {
      "organizationId": "org_fixture",
      "appId": "app_topolo_docs",
      "name": "workflow integration reference",
      "isDefault": true
    },
    "confirm": true
  }
}

Captured local handler response · HTTP 201:

{
  "success": true,
  "message": "Workspace created",
  "data": {
    "workspace": {
      "id": "ws_created_workflow",
      "appId": "app_topolo_docs",
      "organizationId": "org_fixture",
      "name": "workflow integration reference",
      "avatar": {
        "kind": "preset",
        "presetId": "orbit"
      },
      "slug": "ws_created_workflow",
      "status": "active",
      "isDefault": true,
      "ownerUserId": "usr_fixture",
      "createdByUserId": "usr_fixture",
      "createdAt": 1,
      "updatedAt": 1,
      "archivedAt": null
    }
  },
  "timestamp": "2026-10-02T14:48:16.402Z"
}

data.workspace is the new canonical record. Preserve its stable id and slug independently of the display name. Creation can fail on organization or per-user limits even when the application is accessible.

Verify the result

• List workspaces for the same application/organization and find the returned id once. Compare name, slug, owner and default state; then discover application resources separately.

Errors and recovery

Captured local refusal · HTTP 403:

{
  "input": {
    "organizationId": "org_other_fixture",
    "appId": "app_topolo_docs",
    "name": "Forbidden workspace"
  },
  "response": {
    "success": false,
    "error": {
      "message": "Workspaces are limited to the active organization",
      "code": "FORBIDDEN",
      "details": null,
      "timestamp": "2026-10-02T14:48:16.394Z"
    }
  }
}

No generic customer Auth archive action is published for this workflow. Discover a published archive operation in the owning application and establish emptiness before planning removal. After an unknown network outcome, list existing workspaces before retrying creation to avoid duplicates.

Evidence boundary

The handler test proves response shape and control flow under the listed simulated dependencies. It does not prove real grant evaluation, durable SQL storage, protected credential-store handoff, target application synchronization or downstream use of a key.