Python SDK: workspaces and members

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. 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

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.

# 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

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:

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

AI

Chat completions through the AI Gateway.

Workspace API reference

The REST endpoints behind these methods.

Workspaces from the CLI

The same actions from the terminal.

CLI

VS Code

SDKs

Python SDK: workspaces and members

Workspaces

Members

Shared applications

Acting on a shared app

Errors

Next steps

AI

Workspace API reference

Workspaces from the CLI

​Workspaces

​Members

​Shared applications

​Acting on a shared app

​Errors

​Next steps

AI

Workspace API reference

Workspaces from the CLI

Workspaces

Members

Shared applications

Acting on a shared app

Errors

Next steps