Users

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

Controle de acesso por persona. Módulo users é exclusivo da persona global — nem tenant-admin (excluído ⏳), technician nem viewer entram por padrão (só via role de exceção users:acao). Token sem role suficiente → 403 NOT_ALLOWED. Isso inclui as rotas de vínculo com tenant (/api/users/:userId/tenants).

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

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",
    "federalTaxId": "52998224725",
    "type": "Admin",
    "jobTitle": "Analista"
  }'

201 Created

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

Erros

Criar ou vincular usuário ao tenant (app-to-app)

POST /service/users — autenticado por ServiceAuthMiddleware (token de serviço, client_credentials). O tenantId nunca vem no corpo: é sempre o do chamador, resolvido do token.

Usado por outros serviços/apps parceiros para provisionar um usuário e já vinculá-lo ao próprio tenant, verificando duplicidade por CPF (federalTaxId) e e-mail:

• Se nem o CPF nem o e-mail existirem em nenhum usuário → cria o usuário (resolvendo/criando a identidade no Keycloak, igual ao POST /api/users) e já o vincula ao tenant do token.
• Se o CPF e o e-mail já existirem e apontarem para o mesmo usuário → não cria nada, nem toca no Keycloak; apenas garante o vínculo com o tenant do token (idempotente).
• Se só um dos dois já existir, ou se apontarem para usuários diferentes → 409 USER_DATA_MISMATCH — nada é criado, atualizado ou vinculado.

Corpo

curl -X POST http://localhost:3000/service/users \
  -H "Authorization: Bearer $SERVICE_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Jane Doe",
    "email": "jane.doe@example.com",
    "federalTaxId": "52998224725",
    "type": "Technician",
    "persona": "technician",
    "jobTitle": "Analista"
  }'

201 Created

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

Erros

Listar usuários

GET /api/users — lista paginada.

Query params

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",
      "federalTaxId": "52998224725",
      "jobTitle": "Analista",
      "type": "Admin",
      "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.

Erros

Editar usuário

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

federalTaxId não é editável (imutável após a criação).

Promover a Global (acesso total, bypass de todo o RBAC — RolesGuard e PermissionGuard) é só { "type": "Global" } aqui. Não requer nenhuma configuração no Keycloak. Só quem já é Global pode chamar este endpoint (Module.Users é exclusivo dessa persona), então só um Global promove outro.

Retorna 200 com o usuário atualizado.

Erros

Remover usuário

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

Erros

Memberships (tenants do usuário)

Gerenciam a quais tenants o usuário pertence. É a origem do escopo de leitura: um usuário só enxerga cooperativas/documentos dos tenants dos quais é membro (ver também Organization Tenants).

O lado inverso — listar os usuários de um tenant — é GET /api/tenants/:tenantId/users (mesma relação user_tenants, pela ótica do tenant). Vincular/desvincular continua sendo via as rotas de usuário acima.

Listar tenants do usuário

GET /api/users/:userId/tenants — retorna os tenants a que o usuário pertence, com a persona atribuída em cada vínculo. 404 USER_NOT_FOUND se o usuário não existir.

{
  "data": [
    {
      "id": "t1b2c3d4-e5f6-4789-a123-456789abcdef",
      "customerId": "c1b2c3d4-e5f6-4789-a123-456789abcdef",
      "appId": "a1b2c3d4-e5f6-4789-a123-456789abcdef",
      "name": "Acme Tenant",
      "active": true,
      "persona": "technician"
    }
  ]
}

persona pode vir null — vínculo sem persona atribuída (legado, sem backfill, ou criado sem reatribuição posterior). Nesse estado o usuário toma 403 em qualquer request feita com aquele tenant ativo, até alguém religar com POST /api/users/:userId/tenants informando a persona.

Vincular usuário a um tenant

POST /api/users/:userId/tenants — upsert: se o vínculo já existir, atualiza a persona em vez de duplicar.

curl -X POST http://localhost:3000/api/users/$USER_ID/tenants \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "tenantId": "t1b2c3d4-e5f6-4789-a123-456789abcdef",
    "persona": "technician"
  }'

201 Created

{
  "userId": "u1b2c3d4-e5f6-4789-a123-456789abcdef",
  "tenantId": "t1b2c3d4-e5f6-4789-a123-456789abcdef"
}

Erros

Desvincular usuário de um tenant

DELETE /api/users/:userId/tenants/:tenantId — idempotente. Retorna 204.

Erros

Escopo de cooperativas do usuário no tenant

Dentro de cada tenant, restringe quais cooperativas aquele usuário específico enxerga — um nível abaixo da membership (ver PLANO-RESTRICAO-ORGANIZACAO-POR-USUARIO.md). Exclusivo da persona global; tenant-admin não configura isso, mesmo tratamento de users.

GET retorna o modo (ALL/RESTRICTED), os ids concedidos e effectiveScope:

{
  "scope": "RESTRICTED",
  "organizationIds": ["o1b2c3d4-e5f6-4789-a123-456789abcdef"],
  "effectiveScope": "RESTRICTED"
}

effectiveScope vira ALL_BY_PERSONA quando o usuário-alvo é tenant-admin nesse tenant — ele enxerga todas as cooperativas independente do que estiver salvo em scope/ organizationIds. É um valor distinto de ALL, pra UI deixar claro que a origem é a persona, não a configuração salva.

PUT substitui o conjunto inteiro — não é add/remove granular:

curl -X PUT http://localhost:3000/api/users/$USER_ID/tenants/$TENANT_ID/organizations \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "scope": "RESTRICTED",
    "organizationIds": ["o1b2c3d4-e5f6-4789-a123-456789abcdef"]
  }'

Retorna 204. Com scope: "ALL", organizationIds é ignorado — nenhum grant precisa existir nesse modo.

Erros