[Vibe Coder #2] O que é uma API e por que as chaves de API devem ser ocultadas?

Na Parte 1, comparei um app a um restaurante: salão (frontend), cozinha (backend) e depósito (DB). Agora vamos abordar o tema que mais causa acidentes no vibe coding: APIs e chaves de API. Todos provavelmente já viram o aviso “Nunca exponha sua chave”, mas são raros os lugares que explicam o que ela é, onde fica e o que acontece quando é exposta. Aqui você entende tudo de uma vez.

Uma API é o balcão de pedidos

API é a sigla de Application Programming Interface, mas você pode esquecer o nome completo. O ponto principal é este. API é o balcão onde programas pedem que outros programas executem tarefas.

Voltando à analogia do restaurante, o cliente não pode entrar na cozinha. Em vez disso, envia um pedido em um formato definido: “Uma sopa de kimchi, menos apimentada.” A cozinha prepara e entrega. Uma API é exatamente esse balcão. Você envia uma requisição no formato definido para o endereço definido e recebe uma resposta no formato definido.

Os apps dos vibe coders têm APIs em duas direções.

• A API do meu app: o balcão que meu frontend usa para solicitar tarefas ao meu backend. A pasta app/api/ mencionada na Parte 1 é exatamente isso.
• A API de terceiros: o balcão que meu app usa para solicitar tarefas ao serviço de outra empresa. Pedir ao ChatGPT para escrever um texto (OpenAI API), exibir um mapa (API de mapas) e processar pagamentos (API de pagamentos) são ações de enviar pedidos ao balcão de outra empresa.

A maioria dos apps criados com vibe coding funciona combinando essas “APIs de terceiros”. E, para fazer um pedido no balcão de outra empresa, há algo indispensável.

Uma chave de API é um cartão corporativo

APIs de terceiros não são balcões gratuitos. Cada requisição à OpenAI gera um custo. Por isso, toda requisição leva uma identificação que informa “Para quem deve ir a cobrança deste pedido?”. Essa é a chave de API: uma string longa e aleatória, como sk-proj-....

A natureza de uma chave de API é exatamente igual à de um cartão corporativo.

• Não importa quem passe o cartão, a cobrança vai para o titular.
• Basta saber o número do cartão para usá-lo. Não há reconhecimento facial nem confirmação de assinatura.
• Por isso, se você deixar o número do cartão em um local público, qualquer pessoa no mundo poderá pagar usando o meu dinheiro.

É por isso que o aviso “oculte sua chave” é tão sério. O vazamento de uma chave não é igual ao vazamento de uma senha. Você pode simplesmente trocar a senha, mas todas as cobranças feitas desde o momento do roubo até a emissão de uma nova chave se acumulam na minha fatura.

O que realmente acontece quando há exposição

É fácil pensar: “Quem encontraria a chave do meu app pequeno?”. Esse é o engano mais perigoso. Quem encontra as chaves não são pessoas, mas bots.

Repositórios públicos de código, como o GitHub, são vasculhados 24 horas por dia por milhares de bots. Se você publicar por engano um código com uma chave em um repositório público, normalmente um bot a coleta em alguns minutos. As chaves coletadas são usadas imediatamente para chamadas gratuitas de IA, pagamentos de mineração de criptomoedas, envio de spam e atividades semelhantes. É por isso que a comunidade continua relatando casos de cobranças de milhões de won em uma única noite.

Outra forma de exposição é aquela tratada na Parte 1: colocar a chave no frontend. Como o código do frontend é enviado ao navegador do usuário, qualquer pessoa pode extrair a chave com um clique direito e “Inspecionar”. Quando você pede à IA “integre a OpenAI”, ela pode inserir a chave diretamente no frontend por conveniência, então é obrigatório conferir pessoalmente.

Onde a chave deve ficar

O princípio já apareceu na Parte 1: segredos ficam no backend. Mais especificamente:

• Escreva a chave no arquivo .env do projeto. Ele é um cofre de valores secretos que somente o backend lê.
• Registre o arquivo .env em .gitignore para que o Git não o acompanhe. Assim, mesmo que você envie o código para o GitHub, a chave permanece apenas no seu computador. Projetos gerados por IA normalmente já fazem isso, mas vale conferir uma vez.
• Um app publicado não consegue ler o .env do seu computador. Por isso, registre a chave separadamente no menu “Environment Variables” do painel do serviço de deploy, como o Vercel. Voltaremos a esse assunto na Parte 4 (deploy).

O Next.js tem outra armadilha. Se o nome de uma variável de ambiente começar com NEXT_PUBLIC_, o valor também será enviado ao frontend. Como o nome indica, ele se torna público. Coloque aqui apenas chaves projetadas para serem expostas, como as usadas para exibir mapas; nunca adicione NEXT_PUBLIC_ a chaves que geram cobrança, como as da OpenAI. Se a IA adicionou isso, já é um sinal de perigo.

Como fazer uma autoverificação do seu app

Estas são três verificações que você pode fazer agora.

1. Inspeção do navegador: no site publicado, clique com o botão direito → Inspecionar e pesquise termos como sk-, key e secret nas abas Network ou Sources. Se sua chave secreta aparecer, ela está exposta.
2. Inspeção do GitHub: se o repositório estiver público (Public), pesquise o início da chave no campo de busca do repositório. Ela também está exposta se tiver permanecido apenas em um commit antigo.
3. Peça uma auditoria à IA: diga “Encontre todos os lugares deste projeto onde uma chave de API ou um valor secreto é enviado ao frontend”. A IA que errou ao criar o projeto também pode encontrá-lo com eficiência.

Se a chave já foi exposta

Não adianta esconder uma chave exposta. Você deve presumir que um bot já a copiou. A ordem é esta.

1. No painel do serviço, exclua (revogue) a chave. O uso indevido para a partir desse momento.
2. Emita uma nova chave e, desta vez, coloque-a apenas em .env e no painel de deploy.
3. Defina o limite de uso (spending limit) do serviço. Ele será o teto do prejuízo no próximo incidente. Esse assunto é detalhado na Parte 7 (explosão da fatura).

Resumo

• Uma API é um balcão de pedidos entre programas, e meu app funciona combinando APIs de terceiros.
• Uma chave de API é um cartão corporativo. Não importa quem a use: a cobrança vem para mim.
• Bots encontram chaves em poucos minutos. “Meu app é pequeno” não é uma defesa.
• A chave deve ficar em apenas dois lugares: .env(localmente) e nas variáveis de ambiente do painel de deploy. Uma chave com cobrança que contenha NEXT_PUBLIC_ é um sinal de perigo.
• Se houver exposição, não esconda: revogue → emita novamente → defina um limite.

A próxima parte é sobre Git. Vamos explicar por que todos recomendam usar Git mesmo quando a IA escreve todo o código e como reverter em um minuto quando a IA estraga um app que estava funcionando.