Set default workspace

Set the single canonical default workspace for an application and organization.

Outcome

Set the single canonical default 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.default.set --detail --json
topolo apps --json
topolo whoami --json
topolo workspaces list topolo-docs --json

Input fields

Field	Required	Meaning
`workspaceId`	Yes	Existing canonical workspace identifier from workspaces.list. Preserve its application and organization boundary.
`organizationId`	Yes	Active organization identifier from credential identity. It does not override the credential context; conflicting organization selections are refused.
`appId`	Yes	Exact target application identifier from credential-scoped discovery. Key grants and workspace policy are evaluated for this application.

Effects

Sets the selected workspace as the single canonical active default for this application and organization. Does not move application content.

Interpret the response

data.workspace is the newly selected default. Existing workspace identifiers and content remain distinct; switching the default is not a data migration.

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:


{
  "workspaceId": "ws_created_minimal",
  "organizationId": "org_fixture",
  "appId": "app_topolo_docs"
}

CLI:


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

MCP:


{
  "tool": "topolo_call_action",
  "arguments": {
    "actionId": "app_topolo_auth.workspaces.default.set",
    "input": {
      "workspaceId": "ws_created_minimal",
      "organizationId": "org_fixture",
      "appId": "app_topolo_docs"
    },
    "confirm": true
  }
}

Captured local handler response · HTTP 200:


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

data.workspace is the newly selected default. Existing workspace identifiers and content remain distinct; switching the default is not a data migration.

Workflow example

Input · payload.json:


{
  "workspaceId": "ws_created_workflow",
  "organizationId": "org_fixture",
  "appId": "app_topolo_docs"
}

CLI:


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

MCP:


{
  "tool": "topolo_call_action",
  "arguments": {
    "actionId": "app_topolo_auth.workspaces.default.set",
    "input": {
      "workspaceId": "ws_created_workflow",
      "organizationId": "org_fixture",
      "appId": "app_topolo_docs"
    },
    "confirm": true
  }
}

Captured local handler response · HTTP 200:


{
  "success": true,
  "message": "Default workspace set",
  "data": {
    "workspace": {
      "id": "ws_created_workflow",
      "appId": "app_topolo_docs",
      "organizationId": "org_fixture",
      "name": "Reviewed 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.403Z"
}

data.workspace is the newly selected default. Existing workspace identifiers and content remain distinct; switching the default is not a data migration.

Verify the result

List workspaces in the same application and organization and require exactly the selected id to be marked default. Refresh after a conflict rather than inferring the resulting default.

Errors and recovery

Record the previous default id before changing it. Rediscover that it remains active and accessible, then plan this same action with the prior id.

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.