> ## Documentation Index > Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt > Use this file to discover all available pages before exploring further. # Multi-tenancy > Como a Lerian isola dados entre tenants em deployments compartilhados. Multi-tenancy permite que um único deployment atenda múltiplos clientes independentes — chamados **tenants** — com isolamento completo de dados entre eles. Cada tenant opera como se tivesse seu próprio ambiente dedicado, mesmo que a infraestrutura subjacente seja compartilhada. Na Lerian, o multi-tenancy está disponível em deployments **SaaS** (sempre ativo) e **BYOC Multi-Tenant**. ### Produtos que suportam multi-tenancy O mesmo modelo de tenant baseado em JWT se aplica em toda a plataforma. Suportados atualmente: | Produto | Suporte multi-tenant | Notas | | ------------------------ | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | | **Midaz** (Ledger + CRM) | ✅ Sim | Organizações, ledgers, contas, transações e saldos são escopados ao tenant. | | **Tracer** | ✅ Sim | Regras, limites, validações e eventos de auditoria são escopados ao tenant. Cada tenant tem seu próprio catálogo de regras e limites. | | **Reporter** | ✅ Sim | Relatórios rodam apenas sobre os dados do tenant chamador. | A integração com qualquer um desses produtos é idêntica do ponto de vista da API — o JWT carrega a claim `tenantId` e o serviço resolve o tenant automaticamente. ## Como funciona *** O isolamento de tenant é garantido na camada de aplicação por meio do seu token de autenticação. 1. Você se autentica via [Access Manager](/pt/platform/access-manager/access-manager) e recebe um JWT. 2. Esse token inclui um claim `tenantId` que identifica o seu tenant. 3. Em cada requisição à API, a plataforma resolve o seu tenant a partir do token automaticamente. 4. Todas as operações — criar organizações, consultar ledgers, registrar transações — são escopadas ao seu tenant. Você nunca precisa passar um identificador de tenant em headers ou no corpo das requisições. O token cuida disso. O multi-tenancy é transparente no nível da API. Seu código de integração é o mesmo seja em single-tenant ou multi-tenant — a única diferença é que deployments multi-tenant exigem autenticação em toda requisição. ## Como o escopo de tenant aparece em cada produto *** O `tenantId` do JWT escopa todo recurso que o usuário chamador pode ver ou criar. O modelo de recursos varia por produto: ### Midaz Um tenant **não** é a mesma coisa que uma [organização](/pt/midaz/organizations). Um único tenant pode criar e gerenciar múltiplas organizações — por exemplo, para representar subsidiárias, filiais regionais ou diferentes unidades de negócio. ``` Tenant (resolvido a partir do JWT) ├── Organização A │ ├── Ledger 1 │ └── Ledger 2 ├── Organização B │ └── Ledger 3 ``` Quando você lista organizações, só enxerga as que pertencem ao seu tenant. O mesmo se aplica a todos os recursos do Midaz — ledgers, contas, transações e saldos são todos escopados ao seu tenant automaticamente. ### Tracer O Tracer escopa seu catálogo diretamente sob o tenant — não há camada de organização. ``` Tenant (resolvido a partir do JWT) ├── Regras ├── Limites ├── Validações └── Eventos de auditoria ``` Quando você lista regras ou limites, só enxerga entradas criadas pelo seu tenant. Validações são executadas contra as regras e limites do próprio tenant, nunca contra os de outro tenant. Eventos de auditoria também são escopados ao tenant — até a verificação da cadeia de hash roda apenas sobre a cadeia do tenant chamador. ### Outros produtos Reporter e o resto da plataforma seguem o mesmo padrão: o tenant é o escopo mais externo, e o JWT é a única fonte de verdade para identificar a qual tenant o chamador pertence. ## Isolamento de dados *** Os dados de cada tenant são isolados no nível de banco de dados. Cada tenant opera em um banco de dados separado, o que significa: * Dados de diferentes tenants nunca são armazenados juntos. * Consultas de um tenant não conseguem alcançar os dados de outro tenant. * Mesmo que dois tenants criem estruturas organizacionais idênticas, seus dados permanecem completamente separados. Esse isolamento é garantido por um middleware que roteia cada requisição para o banco de dados correto com base no claim `tenantId` do seu JWT. Não existe caminho na API para contornar isso. Operadores BYOC podem escolher entre isolamento por banco de dados ou por schema, dependendo dos requisitos de infraestrutura. Veja [Modos de isolamento](#modos-de-isolamento) abaixo. ## Modos de isolamento *** Operadores BYOC escolhem o quão fortemente os tenants são isolados na camada de armazenamento. A escolha é feita **por serviço**, então diferentes produtos — ou até diferentes tenants no mesmo produto — podem usar modos diferentes. * **`DATABASE`** — cada tenant recebe um **banco de dados dedicado**. Isolamento máximo, custo mais alto. * **`SCHEMA`** — cada tenant recebe um **schema dedicado** dentro de um banco de dados compartilhado. Densidade eficiente, custo mais baixo. ### DATABASE vs. SCHEMA | Dimensão | `DATABASE` | `SCHEMA` | | :---------------------------- | :-------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------- | | **Isolamento físico** | Completo — banco de dados separado por tenant. | Lógico — schema separado dentro de um banco de dados compartilhado. | | **Blast radius** | Confinado ao banco de dados de um único tenant. | Mais amplo — um incidente no nível do banco de dados pode afetar todos os tenants daquela instância. | | **Restore seletivo** | Restaure um tenant de forma independente, incluindo point-in-time recovery. | Mais difícil — restores operam sobre o banco de dados compartilhado; o restore por tenant exige extrair um único schema. | | **Custo** | Mais alto — a infraestrutura escala por tenant. | Mais baixo — os tenants compartilham uma instância de banco de dados. | | **Isolamento de performance** | Forte — os tenants não competem dentro do mesmo banco de dados. | Mais fraco — os tenants compartilham os recursos da instância e podem competir entre si. | | **Melhor para** | Tenants grandes, regulados, de alto volume ou sensíveis a noisy neighbor. | Muitos tenants menores, onde densidade e eficiência de custo importam. | ### Blast radius O **blast radius** é o escopo de tenants afetados quando algo dá errado — uma migration que falha, um índice corrompido, uma query descontrolada ou um restore. No modo `DATABASE`, o blast radius é um único tenant, porque cada tenant é fisicamente separado. No modo `SCHEMA`, o blast radius é mais amplo, porque os tenants compartilham uma instância de banco de dados e, portanto, compartilham sua superfície de falha e manutenção. Minimizar o blast radius é a principal razão para colocar tenants regulados ou de alto valor no modo `DATABASE`. ### Outros datastores A distinção entre `DATABASE` e `SCHEMA` acima se aplica ao PostgreSQL. Outros datastores aplicam o isolamento de tenants de forma diferente: * **MongoDB** usa um **banco de dados separado por tenant** (um banco de dados por `tenantId`). Isso se aplica tanto no modo `DATABASE` quanto no modo `SCHEMA` — o MongoDB não usa schemas, então a unidade de isolamento é sempre um banco de dados dedicado nomeado a partir do `tenantId`. * **RabbitMQ** usa um **virtual host (vhost) separado por tenant**. O vhost é provisionado automaticamente durante o fluxo de onboarding do tenant e é nomeado a partir do `tenantId`. As credenciais têm escopo no vhost, então um consumidor mal configurado não consegue acessar as filas de outro tenant. **Restore seletivo:** o restore por tenant é suportado para PostgreSQL e MongoDB — ambos têm escopo por tenant. O estado do RabbitMQ é efêmero por natureza, então "restaurar" significa reprovisionar o vhost e reentregar quaisquer mensagens não confirmadas (unacked) a partir do armazenamento persistente quando aplicável. ### Migrando de SCHEMA para DATABASE Um tenant pode ser promovido do modo `SCHEMA` para o `DATABASE` à medida que cresce, sem reemitir tokens nem alterar a identidade do tenant — o isolamento é uma propriedade do *serviço*, não do tenant. A plataforma provisiona um novo banco de dados isolado para o tenant e executa as migrations, conforme descrito em [provisionamento automático](/pt/multi-tenancy/auto-provisioning). Os dados do tenant são movidos do schema no banco de dados compartilhado para o novo banco de dados dedicado. O registro de serviço do tenant é atualizado para a configuração do modo `DATABASE`. A claim `tenantId` permanece inalterada, então as integrações continuam funcionando sem modificação. Começar no modo `SCHEMA` e promover tenants individuais para o modo `DATABASE` mantém os custos iniciais baixos enquanto reserva bancos de dados dedicados para os tenants que precisam deles. Veja [Casos de uso](/pt/multi-tenancy/use-cases) para exemplos práticos. ## O que isso significa para você *** ### Se você é um cliente SaaS Nada muda na forma como você usa a API. Autentique, obtenha seu token e faça requisições. A plataforma cuida do isolamento de forma transparente. Você não precisa gerenciar identificadores de tenant nem se preocupar com vazamento de dados entre clientes. ### Se você é um operador BYOC rodando multi-tenant Você configura quais tenants existem e como seus bancos de dados são provisionados. Seus clientes se autenticam pelo Access Manager e recebem tokens escopados. A plataforma roteia cada requisição para o banco de dados do tenant correto automaticamente. ### Se você está rodando single-tenant (BYOC ou desenvolvimento local) O multi-tenancy é desabilitado por padrão. Sua configuração existente continua funcionando sem alterações. Nenhum claim de tenant no JWT é necessário, e a autenticação pode ser opcional dependendo da sua configuração. ## Configuração (operadores BYOC) *** O multi-tenancy é desabilitado por padrão em cada produto. Para habilitá-lo, defina `MULTI_TENANT_ENABLED=true` no ambiente de cada produto que você quer rodar em modo multi-tenant (Midaz, Tracer, Reporter). Uma vez habilitado, o produto requer autenticação em cada requisição e um endpoint do serviço de multi-tenancy acessível. ### Configurações principais Essas variáveis se aplicam a todo produto com suporte a multi-tenant (Midaz Ledger, Midaz CRM, Tracer, Reporter): | Variável | Descrição | Padrão | | :-------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------- | :------ | | `MULTI_TENANT_ENABLED` | Habilita o modo multi-tenant. Quando `false`, a plataforma roda em modo single-tenant. | `false` | | `MULTI_TENANT_URL` | URL do endpoint do serviço de multi-tenancy. Obrigatório quando o multi-tenant está habilitado. | — | | `MULTI_TENANT_SERVICE_API_KEY` | API key para autenticar com o serviço de multi-tenancy. Obrigatória quando o multi-tenant está habilitado. | — | | `MULTI_TENANT_CONNECTIONS_CHECK_INTERVAL_SEC` | Frequência (segundos) com que a plataforma revalida as configurações dos tenants a partir do serviço. | — | | `MULTI_TENANT_CACHE_TTL_SEC` | Por quanto tempo (segundos) a configuração de um tenant é cacheada localmente antes de ser buscada novamente. Use `0` para desabilitar o cache. | `120` | ### Circuit breaker Protege contra indisponibilidades do serviço de multi-tenancy falhando rápido quando o serviço está indisponível: | Variável | Descrição | Padrão | | :----------------------------------------- | :--------------------------------------------------------------------------------- | :----- | | `MULTI_TENANT_CIRCUIT_BREAKER_THRESHOLD` | Falhas consecutivas antes de o circuito abrir. | `5` | | `MULTI_TENANT_CIRCUIT_BREAKER_TIMEOUT_SEC` | Por quanto tempo (segundos) o circuito permanece aberto antes de tentar novamente. | `30` | ### Cache no Redis O modo multi-tenant usa o Redis para cachear as configurações dos tenants entre instâncias: | Variável | Descrição | Padrão | | :---------------------------- | :--------------------------------------- | :------ | | `MULTI_TENANT_REDIS_HOST` | Hostname do servidor Redis. | — | | `MULTI_TENANT_REDIS_PORT` | Porta do servidor Redis. | `6379` | | `MULTI_TENANT_REDIS_PASSWORD` | Senha de autenticação do Redis. | — | | `MULTI_TENANT_REDIS_TLS` | Habilita TLS para a conexão com o Redis. | `false` | ### Configurações específicas do CRM Essas variáveis estão disponíveis apenas no componente CRM e controlam o comportamento do pool de conexões para conexões de banco de dados multi-tenant: | Variável | Descrição | Padrão | | :------------------------------ | :--------------------------------------------------------------------------------------- | :----- | | `MULTI_TENANT_TIMEOUT` | Timeout (segundos) do cliente HTTP para as requisições ao serviço de multi-tenancy. | `30` | | `MULTI_TENANT_MAX_TENANT_POOLS` | Número máximo de pools de conexão de banco de dados concorrentes (um por tenant ativo). | `100` | | `MULTI_TENANT_IDLE_TIMEOUT_SEC` | Por quanto tempo (segundos) antes de um pool de conexões de tenant inativo ser removido. | `300` | Para a maioria dos deployments, os valores padrão funcionam bem. Ajuste `MULTI_TENANT_CACHE_TTL_SEC` e `MULTI_TENANT_CONNECTIONS_CHECK_INTERVAL_SEC` com base em quão frequentemente você adiciona ou modifica tenants — valores menores significam propagação mais rápida das mudanças de tenants, valores maiores reduzem a carga sobre o serviço de multi-tenancy. `MULTI_TENANT_ENABLED=true` requer `PLUGIN_AUTH_ENABLED=true`. A autenticação precisa estar ativa para que o isolamento de tenants funcione — a plataforma resolve os tenants a partir do claim do JWT. ## Páginas relacionadas *** Como os bancos de dados, o broker e as credenciais de um tenant são provisionados. Quando escolher isolamento DATABASE vs. SCHEMA, com um caminho de migração. Entenda as diferenças entre SaaS, BYOC Single-Tenant e BYOC Multi-Tenant. Saiba mais sobre as garantias de isolamento de tenant e o modelo de responsabilidade compartilhada. Entenda como a autenticação e a resolução de tenant baseada em JWT funcionam. Saiba como as organizações são estruturadas dentro de um tenant.