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

# Workspaces

> Crea workspace, invita membri, gestisci ruoli e condividi applicazioni all'interno di un team.

<Info>
  I workspace sono esposti dal modulo `api.workspaces` — una novità della v4. Sono disponibili sui piani **Standard, Pro ed Enterprise**.
</Info>

## Creare un workspace

```typescript theme={null}
const { id: workspaceId } = await api.workspaces.create({ name: "Acme" });
```

Il `name` deve essere lungo da 1 a 32 caratteri.

## Elencare i workspace

`api.workspaces.list()` restituisce ogni workspace in cui l'utente autenticato è proprietario o membro.

```typescript theme={null}
const workspaces = await api.workspaces.list();

for (const ws of workspaces) {
    console.log(
        `${ws.name} (${ws.memberList.length} members, ${ws.applicationList.length} apps)`,
    );
}
```

<Warning>
  Nella v3 `ws.members` e `ws.applications` contenevano array di dati grezzi. Nella v4 questi sono ora **moduli** (`ws.members.add(...)`, `ws.applications.add(...)`). Gli array grezzi sono stati spostati in `ws.memberList` e `ws.applicationList`.
</Warning>

## Recuperare un singolo workspace

```typescript theme={null}
const workspace = await api.workspaces.fetch(workspaceId);

console.log(workspace.id);
console.log(workspace.name);
console.log(workspace.owner);
console.log(workspace.createdAt);
console.log(workspace.memberList);
console.log(workspace.applicationList);
```

## Invitare membri

Invitare un membro è un handshake in due fasi — l'invitato dimostra il proprio consenso generando un codice a breve durata (5 minuti) dal **suo** client, e il proprietario lo consuma.

```typescript theme={null}
// 1. From the invitee's own SDK client
const otherApi = new SquareCloudAPI(process.env.OTHER_USER_API_KEY!);
const code = await otherApi.workspaces.generateInviteCode();

// 2. From the workspace owner's client
await workspace.members.add(code, "maintain");
```

Ruoli validi per l'argomento `group`:

| Ruolo      | Descrizione                                                          |
| ---------- | -------------------------------------------------------------------- |
| `view`     | Accesso in sola lettura                                              |
| `manager`  | Gestione delle applicazioni                                          |
| `maintain` | Gestione delle applicazioni + membri di livello inferiore al proprio |
| `admin`    | Amministrazione completa                                             |

<Note>
  Il ruolo `owner` non può essere assegnato tramite l'API — il trasferimento di proprietà non è esposto.
</Note>

## Modificare il ruolo di un membro

```typescript theme={null}
await workspace.members.update("1234567890abcdef1234567890abcdef", "admin");
```

## Rimuovere un membro

```typescript theme={null}
await workspace.members.remove("1234567890abcdef1234567890abcdef");
```

<Note>
  Solo il proprietario del workspace può rimuovere i membri.
</Note>

## Condividere applicazioni

```typescript theme={null}
await workspace.applications.add("abc123def456abc123def456");
await workspace.applications.remove("abc123def456abc123def456");
```

## Abbandonare o eliminare un workspace

```typescript theme={null}
// As a member
await workspace.leave();

// As the owner (irreversible)
await workspace.delete();
```

Puoi anche eliminare o abbandonare tramite ID direttamente dal modulo:

```typescript theme={null}
await api.workspaces.delete(workspaceId);
await api.workspaces.leave(workspaceId);
```