Múltiplas Contas: Supabase & Vercel CLI (Isolamento de Tokens)
Índice do Manual
Para um especialista de software ou desenvolvedor solo (freelancer B2B) de alto nível, o cenário arquitetural padrão não é possuir apenas um projeto, mas sim orquestrar simultaneamente dezenas de SaaS e E-commerces para clientes diferentes.
Frequentemente, cada cliente possui sua própria organização separada e seu próprio login (conta independente) dentro do Supabase, seja por exigência de Compliance ou faturamento isolado.
O erro amador neste cenário é tentar usar o comando clássico supabase login. Esse comando salva as credenciais de uma única conta de forma global na sua máquina (geralmente em ~/.supabase/). Quando você precisa dar manutenção urgente no sistema do "Cliente A" e logo em seguida subir uma atualização no banco de dados do "Cliente B", você é forçado a rodar supabase logout, gerar um novo link de login, autenticar no navegador e rezar para não ter logado na conta errada.
Isso destrói a produtividade e abre uma margem perigosa para rodar uma Migration em produção no cliente errado.
Documentamos abaixo o Padrão de Isolamento por Token para gerenciar contas infinitas do Supabase simultaneamente.
1. O Fim do Login Global
A primeira regra nesta arquitetura é: nunca mais utilize o comando supabase login na sua máquina de trabalho.
Se você possui múltiplos clientes, a autenticação global torna-se um risco operacional. Em vez disso, nós passaremos a utilizar as Variáveis de Ambiente (Environment Variables) injetadas diretamente no diretório de cada cliente.
Quando o Supabase CLI detecta a presença da variável SUPABASE_ACCESS_TOKEN no terminal, ele ignora completamente a configuração global e assume instantaneamente a identidade daquele token.
2. Geração dos Tokens de Acesso Pessoal (PAT)
Para cada conta/cliente diferente, você (ou o cliente) deve gerar um token de acesso invisível.
- Acesse o painel do Supabase com a conta do "Cliente A".
- Vá em Access Tokens nas configurações da conta (Account Settings).
- Gere um novo token (ex:
Gerenciamento_ClienteX_SaaS_2026). - Copie esse token que começa com
sbp_.... (Ele só aparecerá uma vez). - Repita o processo para as contas dos outros clientes.
3. Isolamento Cirúrgico por Projeto
A única forma segura, definitiva e exigida em arquiteturas de múltiplas frentes para injetar este token no projeto é automatizar a troca de contexto a nível de Sistema Operacional, utilizando o direnv.
Injeções manuais via terminal ou depender unicamente da sua própria memória (ou usar empacotadores fracos como dotenv-cli) abrem uma margem inaceitável para erros operacionais e são práticas proibidas neste cenário.
O direnv é uma extensão profunda de terminal (compatível com Linux, Mac, Zsh e Windows/PowerShell) que intercepta o simples comando de navegação de pastas (cd). A mágica arquitetural dele é brutal: ele injeta variáveis de ambiente na memória apenas quando você entra em uma pasta, e as descarrega automaticamente assim que você sai dela.
Como implementar a malha de segurança:
Fase 1: Setup da Máquina (Uma única vez na vida)
- Instalação das CLIs Globais: Caso seu ambiente seja novo, instale os pacotes oficiais da Vercel e do Supabase globalmente via NPM:
npm install -g vercel supabase
- Instalação do direnv: Instale a ferramenta de variáveis via Winget no PowerShell:
winget install direnv
- Em seguida, você precisa avisar ao PowerShell que o
direnvexiste toda vez que você abrir o terminal. Digitenotepad $PROFILEno seu terminal. (O$PROFILEé apenas um arquivo de texto oculto que o PowerShell lê toda vez que é iniciado). - O Bloco de Notas vai abrir. Adicione a seguinte linha mágica no final desse arquivo de texto:
Invoke-Expression (direnv hook powershell | Out-String)
- Salve o arquivo de texto, feche o Bloco de Notas e reinicie o seu terminal. Pronto, as CLIs e o escudo de segurança estão instalados globalmente!
Fase 2: Setup do Projeto (Sempre que criar um SaaS novo)
- Na raiz da pasta do seu novo projeto (ex: "Cliente A"), crie um arquivo oculto chamado
.envrc. - Insira as exportações explícitas dos tokens (Supabase e Vercel) dentro dele:
# Token de acesso à Conta do Cliente A
# (Para linkar o banco de Staging/Homologação)
export SUPABASE_ACCESS_TOKEN="sbp_xxxxxxxxxxxx_token_do_cliente_A"
# Token de acesso à Hospedagem (Vercel) do Cliente A
# (Para puxar as chaves de Staging)
export VERCEL_TOKEN="vR_xxxxxxxxxxxxxxxxxxxx_da_vercel"
- Ao salvar o arquivo, o terminal bloqueará a execução dele por segurança. Você DEVE rodar o comando abaixo para estabelecer a relação de confiança com essa nova pasta:
direnv allow
O Fluxo de Isolamento na Prática: Assim que você digitar cd projeto-cliente-a, o token do Cliente A é injetado silenciosamente na raiz do seu terminal. Você pode então rodar os comandos administrativos sem medo.
O comando de linkagem você roda uma única vez na vida (para amarrar a pasta local ao projeto da nuvem):
supabase link --project-ref abcdefg
E no dia a dia, você roda apenas os comandos curtos e rápidos, pois o projeto já está linkado e o token já está injetado:
supabase db push
Eles rodarão estritamente com a identidade do Cliente A.
No momento exato em que você digitar cd ../projeto-cliente-b, o direnv descarrega o Token do Cliente A da memória e injeta o Token do Cliente B. O isolamento de contexto passa a ser executado pelo simples ato de navegar entre os projetos. Você elimina por completo a chance matemática de subir o banco de dados errado em produção.
O Veredito Arquitetural
Ao eliminar a autenticação global e forçar a injeção do SUPABASE_ACCESS_TOKEN a nível de diretório, nós eliminamos o gargalo da troca constante de contas no navegador.
Mais importante que a velocidade, estabelecemos uma fronteira de segurança impermeável. É fisicamente impossível executar uma alteração destrutiva no banco de dados de um cliente acreditando estar em outro, pois a permissão de acesso existe exclusivamente dentro dos limites daquela pasta. Esta é a disciplina de engenharia esperada ao orquestrar múltiplos SaaS em altíssima escala.
Agora que você domina a arte de isolar os dados de clientes diferentes, é hora de darmos um passo adiante: entender como o código flui e é testado de forma segura dentro de um mesmo cliente.
No próximo capítulo, vamos desmistificar a fundação da nossa esteira de desenvolvimento e por que todo projeto nasce quebrado em três mundos diferentes. Leia: O Ciclo de Vida do Código: Local, Staging e Produção.