# Workspaces

> Um workspace por cliente final do seu app: criar, listar, renomear e desativar.

Fonte: https://metahub.matratecnologia.com/docs/workspaces

Um workspace representa um cliente final do seu app. O `externalId` é o id desse cliente no seu sistema; o `id` é do hub.

| Método e rota | O que faz | Respostas |
|---|---|---|
| `GET /v1/me` | Devolve o app da chave (`{ app: { id, name } }`) | 200 |
| `POST /v1/workspaces` | Cria o workspace ou devolve o existente | 201 criado, 200 já existia |
| `GET /v1/workspaces` | Lista (paginada); filtro opcional `externalId` | 200 |
| `GET /v1/workspaces/:workspaceId` | Busca um workspace | 200, 404 |
| `PATCH /v1/workspaces/:workspaceId` | Renomeia (`{ name }`) | 200, 404 |
| `POST /v1/workspaces/:workspaceId/deactivate` | Desativa; repetir é seguro | 200, 404 |

Corpo do `POST`, sem campos extras (campo desconhecido é rejeitado):

```json
{ "externalId": "cliente-123", "name": "Clínica Exemplo" }
```

`externalId`: 1 a 128 caracteres entre `A-Z a-z 0-9 . _ : -`. `name`: 1 a 200 caracteres.

**Idempotência.** A chave natural é `(app, externalId)`. Chamar o `POST` de novo com o mesmo `externalId` devolve **200** com o workspace existente e **não altera o nome**; só a primeira chamada responde 201. Isso vale também para chamadas concorrentes. Use `PATCH` para renomear.

Resposta de um workspace:

```json
{
  "workspace": {
    "id": "...",
    "externalId": "cliente-123",
    "name": "Clínica Exemplo",
    "status": "active",
    "createdAt": "2026-10-22T15:00:00.000Z",
    "updatedAt": "2026-10-22T15:00:00.000Z"
  }
}
```

`status` é `active` ou `disabled`.