Organization Tenants

Define quais tenants alcançam cada cooperativa. É o que faz a trava de acesso funcionar: um usuário só enxerga as cooperativas (e os documentos delas) dos tenants dos quais faz parte. Enquanto uma cooperativa não tiver vínculo com nenhum tenant do usuário, ela permanece invisível para ele.

Desde 2026-09-03 esse vínculo também governa as chamadas app-to-app: um token de serviço só alcança as cooperativas vinculadas ao seu próprio tenant (ver Escopo por organização).

O mesmo vínculo é gerenciado por dois contextos, com regras diferentes:

• Administrativo (/api/*) — o tenant vem da rota, então um administrador vincula qualquer cooperativa a qualquer tenant. Exclusivo da persona global.
• App-to-app (/service/*) — o tenant é sempre o do chamador (resolvido do token de serviço pelo ServiceAuthMiddleware) e nunca vem no corpo. Um serviço só vincula/desvincula cooperativas ao próprio tenant. É como um serviço adquire alcance, e por isso essas rotas consultam a base inteira.

Controle de acesso por persona. As rotas /api deste módulo são exclusivas da persona global (decisão de produto de 2026-09-04): o vínculo define o alcance de um tenant, no mesmo nível de Tenants — quem administra um tenant não amplia o próprio alcance. tenant-admin está em TENANT_ADMIN_EXCLUDED_MODULES, e nenhuma outra persona tem o módulo na matriz. Liberação pontual só por role de exceção (organization-tenants:create), e modulo:acao:deny bloqueia. Token sem isso → 403 NOT_ALLOWED. As rotas /service/* não passam por esse controle.

A leitura pelo lado do tenant (GET /api/tenants/:tenantId/organizations) é anterior a este módulo e continua sob tenants:read — ver Tenants.

Vincular cooperativa ao tenant (admin)

POST /api/tenants/:tenantId/organizations

Passa a dar ao tenant alcance sobre a cooperativa informada. Idempotente: se o vínculo já existir, responde 201 do mesmo jeito, sem duplicar.

Params

Corpo

curl -X POST \
  http://localhost:3000/api/tenants/$TENANT_ID/organizations \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "organizationId": "'$ORGANIZATION_ID'" }'

201 Created

{
  "organizationId": "o1b2c3d4-e5f6-4789-a123-456789abcdef",
  "tenantId": "t1b2c3d4-e5f6-4789-a123-456789abcdef"
}

Erros

Desvincular cooperativa do tenant (admin)

DELETE /api/tenants/:tenantId/organizations/:organizationId

O tenant deixa de alcançar a cooperativa. Idempotente: se não houver vínculo, ainda responde 204.

curl -X DELETE \
  http://localhost:3000/api/tenants/$TENANT_ID/organizations/$ORGANIZATION_ID \
  -H "Authorization: Bearer $ACCESS_TOKEN"

204 No Content — vínculo removido (ou já inexistente).

Erros

Listar tenants de uma cooperativa

GET /api/organizations/:organizationId/tenants

Leitura inversa de GET /api/tenants/:tenantId/organizations — quais tenants alcançam esta cooperativa. Alimenta o painel de vínculos na tela de detalhe da cooperativa.

curl http://localhost:3000/api/organizations/$ORGANIZATION_ID/tenants \
  -H "Authorization: Bearer $ACCESS_TOKEN"

200 OK

{
  "data": [
    {
      "id": "t1b2c3d4-e5f6-4789-a123-456789abcdef",
      "customerId": "c1b2c3d4-e5f6-4789-a123-456789abcdef",
      "appId": "a1b2c3d4-e5f6-4789-a123-456789abcdef",
      "name": "Acme Tenant",
      "description": null,
      "active": true,
      "metadata": null,
      "keycloakClientId": "acme-tenant",
      "allowedScopes": [],
      "createdAt": "2026-09-04T12:00:00.000Z",
      "updatedAt": null
    }
  ]
}

Erros

Listar cooperativas de um tenant

GET /api/tenants/:tenantId/organizations — retorna as cooperativas alcançadas pelo tenant. Exige tenants:read (não organization-tenants:read): a rota é anterior a este módulo e não foi migrada para não quebrar quem já a consome.

curl http://localhost:3000/api/tenants/$TENANT_ID/organizations \
  -H "Authorization: Bearer $ACCESS_TOKEN"

200 OK

{
  "data": [
    {
      "id": "o1b2c3d4-e5f6-4789-a123-456789abcdef",
      "name": "Cooperativa Recicla Já",
      "alias": null,
      "federalTaxId": "12345678000190",
      "active": true,
      "listed": true
    }
  ]
}

Erros

App-to-app (/service)

O tenant é sempre o do chamador, resolvido do token de serviço — nunca vem na rota nem no corpo.

Vincular cooperativa ao tenant autenticado

POST /service/organizations/:organizationId/tenants

curl -X POST \
  http://localhost:3000/service/organizations/$ORGANIZATION_ID/tenants \
  -H "Authorization: Bearer $SERVICE_ACCESS_TOKEN"

201 Created

{
  "organizationId": "o1b2c3d4-e5f6-4789-a123-456789abcdef",
  "tenantId": "t1b2c3d4-e5f6-4789-a123-456789abcdef"
}

Erros

Desvincular cooperativa do tenant autenticado

DELETE /service/organizations/:organizationId/tenants

curl -X DELETE \
  http://localhost:3000/service/organizations/$ORGANIZATION_ID/tenants \
  -H "Authorization: Bearer $SERVICE_ACCESS_TOKEN"

204 No Content — vínculo removido (ou já inexistente).

Erros