Users

Perfis locais vinculados a uma identidade do Keycloak (idIdentity = sub). Base path: /api/users · autenticação de usuário · header Authorization: Bearer <token>.

Método	Rota	Scope	Resource	Sucesso
`POST`	`/api/users`	`create`	`resource:users`	`201`
`GET`	`/api/users`	`read`	`resource:users`	`200`
`GET`	`/api/users/:id`	`read`	`resource:users_id`	`200`
`PUT`	`/api/users/:id`	`update`	`resource:users_id`	`200`
`DELETE`	`/api/users/:id`	`delete`	`resource:users_id`	`204`

Criar usuário

POST /api/users — resolve a identidade no Keycloak pelo e-mail (que é o login) e a vincula ao perfil local.

Se já existe um usuário com aquele e-mail no Keycloak, o sub dele é reaproveitado como idIdentity.
Se não existe, a identidade é criada no Keycloak (habilitada, sem senha, com as required actions UPDATE_PASSWORD e VERIFY_EMAIL) e um e-mail de definição de senha é enviado. Se o envio falhar (ex.: SMTP fora do ar), o usuário ainda é criado — a required action fica pendente e o e-mail pode ser reenviado pelo console do Keycloak.

O idIdentity não é enviado no corpo: ele é derivado do Keycloak.

Corpo

Campo	Tipo	Obrigatório	Regras
`name`	string	sim	mín. 1 caractere
`email`	string	sim	e-mail válido, único
`type`	enum	sim	`Admin` \| `Technician` \| `Cooperative`
`organizationsIds`	string[]	não
`customerId`	uuid	não	pode ser `null`; se informado, Customer existente (`404` se não existir)

curl -X POST http://localhost:3000/api/users \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Jane Doe",
    "email": "jane.doe@example.com",
    "type": "Admin"
  }'

201 Created

{
  "id": "u1b2c3d4-e5f6-4789-a123-456789abcdef",
  "idIdentity": "a3f5c9d2-keycloak-sub",
  "name": "Jane Doe",
  "email": "jane.doe@example.com",
  "type": "Admin",
  "organizationsIds": [],
  "customerId": null,
  "createdAt": "2026-07-10T12:00:00.000Z",
  "updatedAt": "2026-07-10T12:00:00.000Z"
}

409 Conflict — já existe um usuário com esse email, ou a identidade encontrada no Keycloak já está vinculada a outro usuário local (idIdentity é único). · 404 Not Found — o customerId informado não existe. · 503 Service Unavailable — não foi possível consultar ou criar a identidade no Keycloak.

O backend fala com a Admin REST API do Keycloak usando o service account do client (client_credentials). O client precisa das roles view-users e manage-users de realm-management no realm — sem elas, toda criação de usuário responde 503.

Listar usuários

GET /api/users — lista paginada.

Query params

Param	Tipo	Padrão	Descrição
`page`	number	`1`	inteiro, mín. 1
`limit`	number	`20`	inteiro, 1 a 100
`name`	string	—	filtro por nome
`email`	string	—	filtro por email
`type`	enum	—	`Admin` \| `Technician` \| `Cooperative`
`customerId`	string	—	filtro por customer

curl "http://localhost:3000/api/users?page=1&limit=20&type=Admin" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

200 OK

{
  "data": [
    {
      "id": "u1b2c3d4-e5f6-4789-a123-456789abcdef",
      "idIdentity": "a3f5c9d2-keycloak-sub",
      "name": "Jane Doe",
      "email": "jane.doe@example.com",
      "type": "Admin",
      "organizationsIds": [],
      "customerId": null,
      "createdAt": "2026-07-10T12:00:00.000Z",
      "updatedAt": "2026-07-10T12:00:00.000Z"
    }
  ],
  "total": 1,
  "totalPages": 1,
  "currentPage": 1
}

Obter usuário por id

GET /api/users/:id — retorna um único usuário. 404 se não existir.

Editar usuário

PUT /api/users/:id — atualização parcial (todos os campos opcionais).

Campo	Tipo	Regras
`name`	string	mín. 1 caractere
`email`	string	e-mail válido
`type`	enum	`Admin` \| `Technician` \| `Cooperative`
`organizationsIds`	string[]
`customerId`	uuid	pode ser `null`; se informado, Customer existente

Retorna 200 com o usuário atualizado; 404 se o usuário — ou o customerId informado — não existir.

Remover usuário

DELETE /api/users/:id — soft delete. Retorna 204 No Content.

Criar usuário

Listar usuários

Obter usuário por id

Editar usuário

Remover usuário

On this page