Groups — SaaS Factory.

O que é um Group

Um Group é um par de (template + conjunto de tenants). Você define uma vez o schema do banco — tabelas, funções, políticas RLS — e o SuperDB replica isso para cada novo tenant que você provisiona via API.

Cada tenant recebe:

• Um schema Postgres dedicado (ex: proj_acme) — fisicamente isolado
• Um JWT secret próprio — tokens de um tenant não funcionam em outro
• Um par de API keys (anon + service role) únicas
• As 5 tabelas de auth clonadas do template
• Um role Postgres dedicado com GRANTs corretos

Quando usar Groups

Use Groups quando você é um ISV (Independent Software Vendor) que vende um SaaS B2B onde:

• Cada cliente (empresa, escola, clínica, escritório) tem dados que nunca podem se misturar com os de outro cliente
• Você precisa de conformidade com LGPD em nível de armazenamento — não apenas via RLS
• Seus clientes exigem poder demonstrar isolamento físico de dados (auditoria, saúde, financeiro, jurídico)
• Você quer provisionar novos clientes programaticamente, sem intervenção manual

Quando NÃO usar Groups

Groups não são a solução para todos os casos. Use um projeto único com RLS quando:

• Você tem um app B2C onde todos os usuários compartilham o mesmo produto (rede social, marketplace, e-commerce)
• A separação de dados por Row Level Security é suficiente para seus requisitos de compliance
• Você não precisa dar aos clientes a garantia de isolamento físico de banco
• O overhead operacional de múltiplos schemas não justifica o benefício

Arquitetura: schema-per-tenant

O SuperDB usa o padrão schema-per-tenant do Postgres. Cada tenant é um namespace separado dentro do mesmo servidor Postgres, com:

-- Projeto template (você modela aqui)
proj_erp_template
  ├── pacientes
  ├── medicos
  ├── atendimentos
  ├── auth_users
  └── auth_sessions

-- Tenant A (provisionado automaticamente)
proj_clinica_sao_paulo
  ├── pacientes       ← cópia exata do template
  ├── medicos
  ├── atendimentos
  ├── auth_users      ← usuários ISOLADOS do tenant A
  └── auth_sessions

-- Tenant B (provisionado automaticamente)
proj_clinica_campinas
  ├── pacientes       ← dados COMPLETAMENTE separados do tenant A
  ├── medicos
  └── ...

Queries entre schemas são fisicamente bloqueadas — o role de serviço de cada tenant só tem acesso ao próprio schema.

LGPD-friendly por design

O isolamento por schema facilita a conformidade com a LGPD em pontos críticos:

• Art. 46 — Segurança: dados de clientes diferentes estão em espaços físicos separados no banco
• Art. 18 — Direito à exclusão: para apagar todos os dados de um cliente, basta DROP SCHEMA proj_acme CASCADE — uma operação atômica e completa
• Art. 37 — Registro de operações: logs de acesso por schema são naturalmente segregados
• Portabilidade: exportar dados de um cliente específico é um pg_dump --schema=proj_acme

Ciclo de vida: Group → Tenants → Deploy

1. Você cria um projeto template no dashboard
   └── Modela as tabelas no SQL Editor
   └── Define as policies RLS
   └── Testa localmente

2. Você cria um Group no Admin UI
   └── Seleciona o projeto template
   └── Gera a API Key do Group (guarde! só aparece uma vez)

3. Seu backend chama POST /groups/v1/:id/tenants
   └── quando um novo cliente se cadastra no SEU SaaS

4. SuperDB responde em ~1-2s com:
   └── tenant.id + tenant.slug
   └── anon_key do tenant (vai pro frontend do cliente)
   └── service_role_key do tenant (fica no seu backend)

5. Você guarda as keys no banco do SEU app
   └── e usa elas nas queries desse cliente específico

As três chaves — qual usar em cada lugar

Esta é a parte que mais confunde, porque um Group envolve três credenciais diferentes e só uma delas provisiona tenant.

Não existe uma management key "de grupo": a management key é sempre de um projeto. Quem manda no grupo é a Group API Key.

Limites e controle

Se o seu ERP tem a Group API Key, ele consegue criar tenants sozinho. O que segura isso hoje:

• Cota pelo plano do template. O group herda o plano do projeto que serve de template, e os tenants inclusos são o mesmo número de projetos daquele plano — Grátis 2, Site 3, Pro 10, Escala 40. No grátis, passar disso para o provisionamento com 402 tenant_quota_exceeded; nos pagos, segue provisionando e cada tenant acima custa R$ 5,00/mês.
• Teto de 100 tenants por grupo, independente do plano. É limite de infraestrutura — cada tenant é um schema no Postgres. Devolve 402 tenant_limit_reached, e subir de plano não destrava.
• A chave só enxerga o próprio grupo. Apontar para o id de outro grupo devolve 403, mesmo com uma chave válida.
• Idempotência por external_id. Reenviar a criação do mesmo cliente devolve 200 com o tenant que já existe, em vez de criar um segundo. É o que protege contra retry de fila e clique duplo.
• A chave é revogável e o grupo pode ter mais de uma — dá para girar a credencial sem parar o provisionamento.
• O group é seu. Você cria em /groups no painel, escolhendo um dos seus projetos como template — projeto de outra conta não aparece e é recusado pela API.

Modelo de billing

O group herda o plano do projeto template, e esse plano já inclui um número de tenants (Grátis 2, Site 3, Pro 10, Escala 40). Cada tenant acima disso custa R$ 5,00/mês, somado à sua fatura — no plano Grátis não há excedente: o provisionamento simplesmente para.

São R$ 5,00 porque o consumo do tenant já é cobrado à parte: banco, arquivos, banda e usuários ativos dele entram nas suas quotas e têm excedente próprio. Esta linha paga o que o tenant é além de consumo — schema isolado, JWT secret próprio, par de chaves e roles.

Groups é auto-atendimento desde 04/08/2026: você cria o group e gera a Group API Key em /groups, no painel, sem falar com ninguém. Antes disso era operação da nossa equipe a cada cliente novo.

Próximos passos

• Referência completa da API Groups →
• Cookbook: construir um SaaS multi-tenant do zero →
• Conceitos: multi-tenant — comparação de estratégias →