Pular para o conteúdo
⚙️ HOW-TO

Criar e gerenciar grupos de projetos

Groups agrupam projetos de um mesmo produto SaaS e habilitam o provisionamento automático de tenants isolados.

O que é um Group

Um Group é uma coleção de projetos vinculados a um único produto SaaS. O Group define um schema template — as tabelas, funções e políticas RLS que todos os tenants desse produto compartilham como estrutura base.

Quando um novo cliente (tenant) se cadastra no seu SaaS, o sistema clona automaticamente o schema template para um schema isolado, provisionando o banco desse cliente em segundos.

Caso de uso: SaaS multi-cliente

Estrutura de um Group "crm-saas"
Group: crm-saas (slug: crm-saas)
│
├── Schema template: proj_crm-saas
│     ├── contacts
│     ├── deals
│     ├── activities
│     └── (RLS policies)
│
├── Tenant: empresa-alpha  → proj_crm-saas_empresa-alpha
├── Tenant: empresa-beta   → proj_crm-saas_empresa-beta
└── Tenant: empresa-gamma  → proj_crm-saas_empresa-gamma

Cada tenant tem um banco Postgres próprio, com o schema e o papel de banco dele. Um cliente não alcança os dados de outro, e o token de um tenant é recusado nos demais.

Como criar um Group

No painel, em Groups, clique em Criar group, dê um nome e escolha um dos seus projetos como template. Na página do group, Gerar chave para o meu backend entrega a Group API Key. O mesmo caminho existe pela API de plataforma, autenticando com a sua própria conta (abaixo).

Antes de criar, tenha um projeto template pronto: é o projeto cujo schema (tabelas, políticas de RLS, funções) será clonado para cada novo cliente.

Enquanto o group existir, o projeto template (e a fonte das versões publicadas) não pode ser excluído: a exclusão responde 409 com o nome do group. Aponte o group para outro template, ou exclua o group, antes.

bash — 1. autenticar com a sua conta
TOKEN=$(curl -s -X POST https://auth.superdb.com.br/platform/v1/signin \
  -H "Content-Type: application/json" \
  -d '{"email":"voce@suaempresa.com.br","password":"..."}' | jq -r .access_token)
bash — 2. criar o group
curl -X POST https://auth.superdb.com.br/platform/v1/groups \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{ "name": "CRM SaaS", "slug": "crm_saas", "template_project_id": "<id do projeto template>" }'
bash — 3. gerar a Group API Key
curl -X POST https://auth.superdb.com.br/platform/v1/groups/$GROUP_ID/api-keys \
  -H "Authorization: Bearer $TOKEN"
# → { "api_key": "sdb_gk_..." }  ← aparece UMA vez. Guarde num cofre.
⚠️

A sdb_gk_… provisiona tenants e devolve as chaves deles: trate como segredo de servidor. Nunca no frontend ou no app.

Provisionar o primeiro tenant

Com o Group criado, você pode provisionar tenants. Veja o guia completo em Provisionar um tenant.

💡

Mudou a estrutura do template? Publique uma versão nova (Publicar versão agora, na página do group, ou POST /groups/v1/:group_id/template/publish): os tenants novos nascem com ela. Publicar não retroage: nos tenants que já existem, rode a migration em cada um, com a management key dele. Detalhes em Publicar uma versão do template.

Essa página ajudou?