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 é terminantemente proibido no código do cliente (Frontend). No backend, ela é restrita a:
- Supabase Edge Functions (Deno): Ao receber Webhooks externos (como Stripe ou WhatsApp) ou disparos de Database Triggers, a requisição não possui um usuário logado na sessão. A
service_role_keyentra em ação na Edge Function para atualizar o banco no nível de sistema. - Exceções Administrativas em Server Actions do Next.js: Operações restritas de super-administração que o RLS bloqueia por design (como a API
auth.admin.inviteUserByEmail()para convidar colaboradores ou resetar contas), SEMPRE precedidas pela checagem manual de autorização do usuário logado no topo da função. - Scripts de migração ou automações executadas via terminal local fechado.
3. A Armadilha do Backend (Server Components e Server Actions Comuns)
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 ou salvar dados corriqueiros.
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 para operações comuns, o Supabase ignorará o RLS. Uma simples busca por "listar pedidos" retornaria os pedidos 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 entre clientes (Cross-Tenant Data Leakage).
A regra de ouro para o Next.js:
Toda busca de Server Component e mutação de Server Action acionada por um usuário deve utilizar a anon_key combinada aos Cookies de Sessão do navegador (usando @supabase/ssr). Desta forma, o servidor age em nome do usuário logado, e o próprio PostgreSQL impõe a filtragem das linhas pelo RLS.
Como Implementar a Exceção Administrativa em Server Actions com Segurança
Se a sua Server Action realmente precisa invocar a API de administração (auth.admin), siga obrigatoriamente este padrão de três etapas:
// app/actions/admin-invite-user.ts
"use server";
import { createServerClient } from "@/lib/supabase/server";
import { createClient } from "@supabase/supabase-js";
export async function inviteEmployeeAction(email: string) {
// 1. Identifica o usuario logado com o client comum (ANON + Cookies)
const supabase = await createServerClient();
const { data: { user }, error: authError } = await supabase.auth.getUser();
if (authError || !user) {
throw new Error("Sessao invalida. Faca login novamente.");
}
// 2. Valida se o usuario logado possui permissao de Administrador no banco
const { data: profile } = await supabase
.from("profiles")
.select("role")
.eq("id", user.id)
.single();
if (profile?.role !== "admin") {
throw new Error("Acesso negado: apenas administradores podem convidar usuarios.");
}
// 3. APENAS com a autorizacao confirmada, instancia o client Service Role
const supabaseAdmin = createClient(
process.env.NEXT_PUBLIC_SUPABASE_URL!,
process.env.SUPABASE_SERVICE_ROLE_KEY!
);
const { data, error } = await supabaseAdmin.auth.admin.inviteUserByEmail(email);
if (error) {
throw new Error(`Falha ao enviar convite: ${error.message}`);
}
return { success: true, invitedUser: data.user };
}
4. O Veredito Arquitetural e Tratamento de Falhas
A arquitetura moderna prevê que a confiança no código do desenvolvedor é 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. - Uso de Service Role sob Demanda Restrita: A
service_role_keysó entra em campo em Edge Functions sem usuário logado (Webhooks externos) ou em Server Actions administrativas com checagem rigorosa derole === 'admin'antes da execução. - Revisão de Código Restrita: Se um robô autônomo de Inteligência Artificial ou um desenvolvedor tentar utilizar a
service_role_keydentro de um Server Component para fazer listagens comuns de tela, 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.