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

# JavaScript SDK: workspaces and members

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

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

Creating workspaces needs a Standard, Pro or Enterprise plan.

Examples use the `api` client from [Creating the client](/en/sdks/js/client#creating-the-client). `workspaceId` is the id of a workspace (`workspaces.list()` lists them), `appId` the id of one of your apps and `memberId` the `id` of a member.

## Workspaces

```typescript theme={"system"}
const { id, name } = await api.workspaces.create("My team");

const workspaces = await api.workspaces.list();
const workspace = await api.workspaces.get(id);

console.log(workspace.name, workspace.owner, workspace.createdAt);

for (const member of workspace.members) {
    console.log(member.id, member.name, member.group, member.joinedAt);
}
for (const app of workspace.applications) {
    console.log(app.id, app.name, app.lang, app.ram);
}

await api.workspaces.leave(id);  // as a member
await api.workspaces.delete(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 `null` 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.inviteCode()`. The code is valid for **5 minutes**.

```typescript theme={"system"}
// The member runs this and sends you the code
const code = await api.workspaces.members.inviteCode();

// The owner adds them with a role
await api.workspaces.members.add(workspaceId, code, "maintain");

await api.workspaces.members.update(workspaceId, memberId, "view");
await api.workspaces.members.remove(workspaceId, memberId);
```

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

## Shared applications

```typescript theme={"system"}
await api.workspaces.apps.add(workspaceId, appId);
await api.workspaces.apps.remove(workspaceId, appId);
```

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 `api.apps` method. `workspaces.get()` and `workspaces.list()` return raw ids, so build it yourself:

```typescript theme={"system"}
const workspace = await api.workspaces.get(workspaceId);

for (const app of workspace.applications) {
    const status = await api.apps.status(`${app.id}-${workspace.id}`);
    console.log(app.name, status.running);
}

// Status of every app of the workspace in one request
const statuses = await api.apps.statusAll({ workspaceId });
```

## Errors

Except `workspaces.get()`, workspace routes send the ids in the request body, so an empty id there is 400 `INVALID_ID` from the server, not a local error.

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