Modelo de isolamento de tenants

Toda API multi-tenant da Vellus Payments segue a mesma regra: o tenant de uma operação vem do claim tenant_id do token, nunca de um campo que o chamador informe no corpo, na query ou na rota. Um tenant autenticado não consegue ler, alterar nem apagar recurso de outro tenant enviando o id dele mesmo — o valor informado é ignorado ou, quando a rota referencia um recurso específico, recusado como se o recurso não existisse.

Essa seção documenta o comportamento esperado por quem integra. O catálogo técnico completo, com a evidência de cada achado e o teste de regressão correspondente, vive em tests/e2e/tenant-isolation/tenant-isolation-cases.yaml no repositório Payments.Core — referência para quem auditar ou revisar, não para quem só consome a API.

Princípio

• Origem do tenant: sempre o claim tenant_id do token de acesso. Nenhum serviço aceita tenantId do corpo, da query ou da rota como fonte de autorização.
• Sem claim de tenant: a requisição recebe 401 (sem autenticação) ou 403 (autenticado, sem o claim), conforme o caso.
• Recurso de outro tenant: a resposta é 404, com a mesma mensagem genérica de recurso inexistente. A API nunca devolve 403 com detalhe nem um corpo diferente para "existe, mas não é seu" — isso revelaria a existência do recurso a quem não tem acesso a ele.

Por serviço

Payments.Buyer — expurgo e política de retenção (v1)

As rotas administrativas de política de retenção e de expurgo de comprador (LGPD, direito de eliminação) exigem que o tenant da rota seja igual ao claim do token: requisição anônima recebe 401, e um administrador de outro tenant recebe 403, antes de qualquer busca pelo comprador. Essas rotas são de uso administrativo interno — não fazem parte da superfície pública da API.

Payments.SplitRules — regras de split (v1)

As operações por {splitRuleId} (PATCH /api/splitrules/{splitRuleId}/activate, .../disable, .../block) exigem o claim de tenant no token. Uma regra de split que pertence a outro tenant responde 404 ("Split Rule não encontrada."), a mesma mensagem de id inexistente — sem distinguir "não existe" de "existe, mas é de outro tenant".

A v1 do SplitRules é legada; a decisão de retirada do código e do roteamento depende da medição de 30 dias de chamadas reais, documentada em Payments.Platform/docs/runbooks/medicao-uso-splitrules-v1.md.

Payments.Sellers (v2)

A mesma regra vale para conta bancária (criação e atualização), listagem filtrada, ativação e confirmação de KYC no provedor, e métodos de pagamento do adquirente: o TenantId/SellerId informado é sobrescrito pelo claim do token antes de qualquer validação, e a resposta nunca distingue "recurso de outro tenant" de "recurso inexistente".

O que muda para quem integra

Não existe forma de operar sobre recurso de outro tenant enviando o tenantId certo no corpo, na query ou na rota: o escopo vem sempre do token. Um integrador que dependa de enviar esse campo manualmente — padrão comum em integrações legadas — deve parar de esperar efeito dele: o valor é ignorado silenciosamente, ou a chamada recebe 404 quando o recurso referenciado na rota pertence a outro tenant.