O Risco Fatal das Chaves: Service Role vs. Anon Key
Índice do Manual
No desenvolvimento de arquiteturas baseadas em Supabase e Next.js, o manuseio de credenciais é o ponto exato onde a negligência técnica destrói sistemas.
Um erro comum em equipes juniores — e um vício perigoso em agentes de Inteligência Artificial — é a confusão operacional entre as duas chaves de API fornecidas pelo Supabase: a Anon Key e a Service Role Key.
Trocar o local de uso dessas chaves não gera apenas um erro no terminal. Usar a chave pública no lugar da privada impede o funcionamento de processos de backend. Pior: vazar a chave privada para o frontend concede controle absoluto do banco de dados para qualquer usuário na internet.
Documentamos abaixo a lei arquitetural sobre o isolamento e o escopo exato de cada chave.
1. Anon Key (A Chave Pública)
A anon_key (Anonymous Key) é a chave projetada exclusivamente para a exposição pública. No Next.js, ela é declarada no arquivo de ambiente com o prefixo público: NEXT_PUBLIC_SUPABASE_ANON_KEY.
O que ela faz?
Ela atua apenas como uma "maçaneta" para a porta do seu banco de dados. Ela permite que a requisição chegue ao Supabase, mas não concede nenhuma permissão automática.
Toda requisição feita com a anon_key bate imediatamente na barreira do RLS (Row Level Security). Se o usuário não estiver logado ou se a política de segurança (Policy) não permitir a leitura, o banco de dados simplesmente retornará uma matriz vazia ou um erro de permissão.
Onde utilizá-la:
- Em qualquer código de Frontend (Client Components do Next.js).
- Quando você deseja que as regras normais de segurança (RLS) sejam aplicadas rigorosamente.
- No momento de realizar login, logout e criar contas de usuários padrões.
2. Service Role Key (A Chave Mestre Administrativa)
A service_role_key é o nível "Deus" (God Mode) da infraestrutura do Supabase. Ela é declarada estritamente como SUPABASE_SERVICE_ROLE_KEY (sem o prefixo NEXT_PUBLIC).
O que ela faz?
Esta chave foi projetada para rotinas administrativas puras. Ela ignora (bypass) 100% das políticas de segurança do RLS.
Se um código utiliza esta chave, ele tem permissão matemática e irrestrita para deletar todos os usuários, apagar todos os bancos de dados e limpar o Storage inteiro, independentemente de quem estiver logado (ou se ninguém estiver logado).
Onde utilizá-la (A Lei):
O uso desta chave é proibido no ecossistema do cliente (Frontend). Seu uso é restrito a:
- Supabase Edge Functions (Deno): Por exemplo, ao receber um Webhook do Stripe confirmando um pagamento, o sistema precisa atualizar o plano do usuário no banco de dados. Como o Webhook é disparado pelo Stripe (e não pelo usuário logado), a
anon_keyseria bloqueada pelo RLS. Aservice_role_keyentra em ação na Edge Function para forçar a atualização da tabela no nível administrativo. - Scripts de migração ou automações executadas via terminal local fechado.
3. A Armadilha do Backend (Server Components)
O erro conceitual mais letal na transição para o Next.js moderno (App Router) é acreditar que, como o código está rodando no Backend (Server Components ou Server Actions), deve-se utilizar a service_role_key para buscar os dados.
Isso é categoricamente falso.
No ecossistema Supabase, a segurança mora no Banco de Dados (RLS), não no servidor web. Se o backend utilizar a chave mestre, o Supabase ignorará o RLS. Uma simples busca por "listar clientes" retornaria os clientes de todas as empresas cadastradas no sistema SaaS, forçando o desenvolvedor a escrever dezenas de filtros manuais no código web, o que invariavelmente gera vazamentos de dados colossais.
A regra arquitetural para o Backend do Next.js:
Para buscar dados de um usuário logado, o backend deve obrigatoriamente utilizar a anon_key (chave pública) combinada aos Cookies de Sessão do navegador (usando a biblioteca nativa @supabase/ssr).
Desta forma, o servidor faz a requisição em nome do usuário, e o próprio banco de dados impõe a segurança (RLS), garantindo que o retorno dos dados seja matematicamente filtrado.
4. O Veredito Arquitetural e Tratamento de Falhas
A arquitetura moderna prevê que a confiança no código é zero. Para evitar falhas, impomos as seguintes barreiras:
- Prevenção de Vazamento Front-End: O Next.js possui uma trava nativa onde apenas variáveis com prefixo
NEXT_PUBLIC_são enviadas ao navegador. A chave mestre nunca deve possuir este prefixo. Se for declarada comoNEXT_PUBLIC_SUPABASE_SERVICE_ROLE_KEY, a infraestrutura está comprometida e o token revogado. - Prevenção de Vazamento Back-End: A
service_role_keysó entra em campo no backend em operações sem usuário logado ou ações estritamente administrativas (como Webhooks e Cron Jobs noturnos). - Revisão de Código Restrita: Se um robô autônomo de Inteligência Artificial ou um engenheiro tentar utilizar a
service_role_keydentro de um Server Component do Next.js para fazer buscas corriqueiras, o código deve ser rejeitado. Toda busca de UI utilizaanon_key+ Cookies.
Dominar o isolamento destas chaves não é um mero detalhe de configuração; é a assinatura de maturidade técnica que separa sistemas amadores de plataformas corporativas blindadas.