> ## Documentation Index
> Fetch the complete documentation index at: https://docs.squarecloud.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Python SDK: workspaces and members

> Create and manage workspaces, invite members, set their roles and share applications with client.workspaces. Act on a shared app with its composite id.

A workspace shares apps with other Square Cloud users, each with a role. `client.workspaces` manages workspaces, `client.workspaces.members` their members and `client.workspaces.apps` the shared apps.

Creating workspaces needs a Standard, Pro or Enterprise plan.

Examples use the `client` from [Creating the client](/en/sdks/py/client#creating-the-client). `workspace_id` is the id of a workspace (`workspaces.list()` lists them), `app_id` the id of one of your apps and `member_id` the `id` of a member.

## Workspaces

```python theme={"system"}
created = client.workspaces.create("My team")
workspace_id = created["id"]

workspaces = client.workspaces.list()
workspace = client.workspaces.get(workspace_id)

print(workspace["name"], workspace["owner"], workspace["createdAt"])

for member in workspace["members"]:
    print(member["id"], member["name"], member["group"], member["joinedAt"])
for app in workspace["applications"]:
    print(app["id"], app["name"], app["lang"], app["ram"])

client.workspaces.leave(workspace_id)   # as a member
client.workspaces.delete(workspace_id)  # as the owner
```

| Field | Description |
| - | - |
| `id` | 32 hex characters (older workspaces keep a 40-character id) |
| `name` | Workspace name (1 to 32 characters) |
| `owner` | Owner's user id |
| `members` | `{ id, name, group, joinedAt }`. `name` is `None` when it cannot be resolved (a deleted account) |
| `applications` | `{ id, name, desc, ram, lang, domain?, custom? }` |
| `createdAt` | Creation date |

The owner cannot leave (400 `CANNOT_LEAVE_OWNER`): delete the workspace instead.

## Members

Adding a member takes an **invite code** that the member generates with `members.invite_code()`. The code is valid for **5 minutes**.

```python theme={"system"}
# The member runs this and sends you the code
code = client.workspaces.members.invite_code()

# The owner adds them with a role
client.workspaces.members.add(workspace_id, code, "maintain")

client.workspaces.members.update(workspace_id, member_id, "view")
client.workspaces.members.remove(workspace_id, member_id)
```

Roles (`group`): `view`, `manager`, `maintain` and `admin`. Calling a method that your role does not allow is 403 `PERMISSION_DENIED`.

## Shared applications

```python theme={"system"}
client.workspaces.apps.add(workspace_id, app_id)
client.workspaces.apps.remove(workspace_id, app_id)
```

A workspace can hold up to 100 apps (400 `APPLICATIONS_LIMIT_REACHED`).

### Acting on a shared app

To act on an app shared with you, pass the composite id `<appId>-<workspaceId>` to any `client.apps` method. `workspaces.get()` and `workspaces.list()` return raw ids, so build it yourself:

```python theme={"system"}
workspace = client.workspaces.get(workspace_id)

for app in workspace["applications"]:
    status = client.apps.status(f"{app['id']}-{workspace['id']}")
    print(app["name"], status["running"])

# Status of every app of the workspace in one request
statuses = client.apps.status_all(workspace_id=workspace_id)
```

## Errors

Workspace routes send the ids in the request body, so an empty id is 400 `INVALID_ID` from the server (not a local error). The exception is `workspaces.get()`, whose id is in the URL path: an empty id fails locally there.

| Status | Code | When |
| - | - | - |
| 400 | `INVALID_NAME` | The name is not 1 to 32 characters |
| 400 | `WORKSPACE_LIMIT_REACHED`, `MEMBERS_LIMIT_REACHED`, `APPLICATIONS_LIMIT_REACHED` | A plan or workspace limit was reached |
| 400 | `INVALID_CODE` | The invite code is missing, malformed or expired |
| 400 | `INVALID_GROUP` | The role is not `view`, `manager`, `maintain` or `admin` |
| 400 | `CANNOT_INVITE_OWNER`, `CANNOT_EDIT_OWNER`, `CANNOT_LEAVE_OWNER` | The action does not apply to the owner |
| 400 | `MEMBER_ALREADY_ADDED`, `APP_ALREADY_IN_WORKSPACE` | Already in the workspace |
| 403 | `UPGRADE_REQUIRED` | The plan cannot create workspaces |
| 403 | `PERMISSION_DENIED` | Your role does not allow the action |
| 404 | `WORKSPACE_NOT_FOUND`, `MEMBER_NOT_FOUND`, `APP_NOT_FOUND` | Not found |

## Next steps

<CardGroup cols={3}>
  <Card title="AI" icon="robot" href="/en/sdks/py/ai">
    Chat completions through the AI Gateway.
  </Card>

  <Card title="Workspace API reference" icon="code" href="/en/api-reference/endpoint/workspace/list">
    The REST endpoints behind these methods.
  </Card>

  <Card title="Workspaces from the CLI" icon="terminal" href="/en/cli-reference/workspaces">
    The same actions from the terminal.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.