Referência da API

Usuários

O catálogo de contas da instalação. Prefixo de administrador.

ADMIN em qualquer método, inclusive na leitura: a lista de contas e de papéis não fica visível para membros.

GET/api/users

Papel: Administrador

As contas da instalação, com papel e espaços de cada uma.

Requisição

curl -s http://localhost:3000/api/users \
  -H "Authorization: Bearer $TOKEN"

Resposta200

[
  {
    "id": "cmt94cjx5000vql01imegem2r",
    "name": "Ana",
    "email": "[email protected]",
    "role": "MEMBER",
    "avatarUrl": null,
    "jobTitle": "Product Owner",
    "timezone": "America/Sao_Paulo",
    "notifyBackupReady": true,
    "hasApiToken": false,
    "apiTokenCreatedAt": null,
    "apiTokenLast4": null,
    "passwordPending": false,
    "lastLoginAt": "2026-08-27T19:50:42.947Z",
    "createdAt": "2026-08-25T20:29:57.593Z",
    "tenants": [
      {
        "id": "cmsp4djx60002p801o7ybpkv7",
        "name": "Pessoal",
        "color": "amber",
        "role": "MEMBER",
        "membership": "MEMBER"
      }
    ]
  }
]

Respostas de erro

Código	Quando acontece
`401`	Sem credencial, ou com uma que não vale mais. Mande o cookie de sessão ou o cabeçalho `Authorization: Bearer`.
`403`	A conta não é administradora. Este prefixo exige `ADMIN` em qualquer método, inclusive na leitura.

POST/api/users

Papel: Administrador

Cria uma conta, opcionalmente já com os espaços de trabalho dela.

Corpo da requisição

Campo	Tipo	Descrição
`name`obrigatório	`string`
`email`obrigatório	`string`
`password`obrigatório	`string`	A senha inicial. Não há envio de e-mail nesta instalação, então combine-a por fora.
`role`obrigatório	`enum`	Papel na INSTALAÇÃO. Decide as rotas que não pertencem a espaço nenhum.ADMIN · MEMBER · VIEWER
`jobTitle`	`string \| null`
`tenants`	`{ tenantId, role }[]`	Pares `{ tenantId, role }`. O papel de dentro do espaço só aceita `MEMBER` ou `VIEWER`.

Requisição

curl -s -X POST http://localhost:3000/api/users \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Bruno",
    "email": "[email protected]",
    "password": "uma senha longa",
    "role": "MEMBER",
    "tenants": [
      { "tenantId": "cmsp4djx60002p801o7ybpkv7", "role": "MEMBER" }
    ]
  }'

const response = await fetch("http://localhost:3000/api/users", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: `Bearer ${token}`,
  },
  body: JSON.stringify({
    name: "Bruno",
    email: "[email protected]",
    password: "uma senha longa",
    role: "MEMBER",
    tenants: [{ tenantId, role: "MEMBER" }],
  }),
});

const user = await response.json();

Resposta201

{
  "id": "cmt94cjx5000vql01imegem2r",
  "name": "Ana",
  "email": "[email protected]",
  "role": "MEMBER",
  "avatarUrl": null,
  "jobTitle": "Product Owner",
  "timezone": "America/Sao_Paulo",
  "notifyBackupReady": true,
  "hasApiToken": false,
  "apiTokenCreatedAt": null,
  "apiTokenLast4": null,
  "passwordPending": false,
  "lastLoginAt": "2026-08-27T19:50:42.947Z",
  "createdAt": "2026-08-25T20:29:57.593Z",
  "tenants": [
    {
      "id": "cmsp4djx60002p801o7ybpkv7",
      "name": "Pessoal",
      "color": "amber",
      "role": "MEMBER",
      "membership": "MEMBER"
    }
  ]
}

Respostas de erro

Código	Quando acontece
`401`	Sem credencial, ou com uma que não vale mais. Mande o cookie de sessão ou o cabeçalho `Authorization: Bearer`.
`403`	A conta não é administradora. Este prefixo exige `ADMIN` em qualquer método, inclusive na leitura.
`409`	Outra conta já usa esse e-mail.
`422`	O corpo não passou pelo schema. O campo `details` traz `fieldErrors` e `formErrors` do zod, campo a campo.

Vale o mais restrito dos dois eixos: um VIEWER da instalação não escreve em lugar nenhum, mesmo sendo MEMBER de um espaço.

PATCH/api/users/[id]

Papel: Administrador

Edita outra conta: nome, e-mail, papel e a redefinição de senha.

Parâmetros de rota

Campo	Tipo	Descrição
`id`obrigatório	`cuid`

Corpo da requisição

Campo	Tipo	Descrição
`name`	`string`
`email`	`string`
`role`	`enum`	ADMIN · MEMBER · VIEWER
`password`	`string`	A REDEFINIÇÃO feita por um administrador. Não pede a senha atual: é o caminho de recuperação desta instalação.
`jobTitle`	`string \| null`

Requisição

curl -s -X PATCH http://localhost:3000/api/users/cmt94cjx5000vql01imegem2r \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "role": "VIEWER" }'

Resposta200

{
  "id": "cmt94cjx5000vql01imegem2r",
  "name": "Ana",
  "email": "[email protected]",
  "role": "VIEWER",
  "avatarUrl": null,
  "jobTitle": "Product Owner",
  "timezone": "America/Sao_Paulo",
  "notifyBackupReady": true,
  "hasApiToken": false,
  "apiTokenCreatedAt": null,
  "apiTokenLast4": null,
  "passwordPending": false,
  "lastLoginAt": "2026-08-27T19:50:42.947Z",
  "createdAt": "2026-08-25T20:29:57.593Z",
  "tenants": [
    {
      "id": "cmsp4djx60002p801o7ybpkv7",
      "name": "Pessoal",
      "color": "amber",
      "role": "MEMBER",
      "membership": "MEMBER"
    }
  ]
}

Respostas de erro

Código	Quando acontece
`401`	Sem credencial, ou com uma que não vale mais. Mande o cookie de sessão ou o cabeçalho `Authorization: Bearer`.
`403`	A conta não é administradora. Este prefixo exige `ADMIN` em qualquer método, inclusive na leitura.
`404`	O recurso não existe, ou já foi apagado.
`409`	Outra conta já usa esse e-mail.
`422`	Sempre sobra um administrador: a instalação não fica sem quem possa devolver acesso.

A redefinição feita aqui derruba TODAS as sessões daquela pessoa: nenhum acesso antigo continua valendo.

DELETE/api/users/[id]

Papel: Administrador

Remove uma conta.

Parâmetros de rota

Campo	Tipo	Descrição
`id`obrigatório	`cuid`

Requisição

curl -s -X DELETE http://localhost:3000/api/users/cmt94cjx5000vql01imegem2r \
  -H "Authorization: Bearer $TOKEN"

Resposta200

{ "deleted": true }

Respostas de erro

Código	Quando acontece
`401`	Sem credencial, ou com uma que não vale mais. Mande o cookie de sessão ou o cabeçalho `Authorization: Bearer`.
`403`	A conta não é administradora. Este prefixo exige `ADMIN` em qualquer método, inclusive na leitura.
`404`	O recurso não existe, ou já foi apagado.
`422`	Sempre sobra um administrador: a instalação não fica sem quem possa devolver acesso.

O último administrador não pode ser removido: a instalação não pode ficar sem quem devolva acesso.

PUT/api/users/[id]/tenants

Papel: Administrador

Define os espaços de trabalho de uma pessoa: a lista FINAL.

É PUT e não PATCH porque o corpo é o conjunto inteiro, como tagIds no formulário do card: o que não vier na lista deixa de ser alcançado.

Parâmetros de rota

Campo	Tipo	Descrição
`id`obrigatório	`cuid`

Corpo da requisição

Campo	Tipo	Descrição
`tenants`obrigatório	`{ tenantId, role }[]`	Espaço fora desta lista deixa de ser alcançado; espaço novo entra com o papel indicado.

Requisição

curl -s -X PUT http://localhost:3000/api/users/cmt94cjx5000vql01imegem2r/tenants \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "tenants": [
      { "tenantId": "cmsp4djx60002p801o7ybpkv7", "role": "MEMBER" },
      { "tenantId": "tenant-pessoal", "role": "VIEWER" }
    ]
  }'

Resposta200

{
  "id": "cmt94cjx5000vql01imegem2r",
  "name": "Ana",
  "email": "[email protected]",
  "role": "MEMBER",
  "avatarUrl": null,
  "jobTitle": "Product Owner",
  "timezone": "America/Sao_Paulo",
  "notifyBackupReady": true,
  "hasApiToken": false,
  "apiTokenCreatedAt": null,
  "apiTokenLast4": null,
  "passwordPending": false,
  "lastLoginAt": "2026-08-27T19:50:42.947Z",
  "createdAt": "2026-08-25T20:29:57.593Z",
  "tenants": [
    {
      "id": "cmsp4djx60002p801o7ybpkv7",
      "name": "Pessoal",
      "color": "amber",
      "role": "MEMBER",
      "membership": "MEMBER"
    }
  ]
}

Respostas de erro

Código	Quando acontece
`401`	Sem credencial, ou com uma que não vale mais. Mande o cookie de sessão ou o cabeçalho `Authorization: Bearer`.
`403`	A conta não é administradora. Este prefixo exige `ADMIN` em qualquer método, inclusive na leitura.
`404`	O recurso não existe, ou já foi apagado.
`422`	O corpo não passou pelo schema. O campo `details` traz `fieldErrors` e `formErrors` do zod, campo a campo.