Segurança de chaves de API de e-mail: permissões, rotação e onde guardá-las

Uma chave de API de e-mail é uma string pequena com muito poder. Quem a tiver pode enviar e-mails do seu domínio, para qualquer pessoa, em seu nome. Chaves vazadas são uma das formas mais comuns de campanhas de phishing acabarem sendo enviadas pela infraestrutura de empresas legítimas.

A boa notícia: alguns hábitos tornam um vazamento improvável e limitam o estrago se ele acontecer mesmo assim. Este guia mostra esses hábitos usando os controles que a Inbixio oferece em cada chave.

O que uma chave da Inbixio pode fazer

Cada chave que você cria em API Keys → Create Api Key (chaves de API → criar chave de API) tem três configurações:

• Name (nome), para sua própria organização, por exemplo prod-auth-service.
• Server Access (acesso ao servidor): All Server (todos os servidores; envia pelo primeiro servidor SMTP que você conectou) ou Selected Server (servidor selecionado; exatamente o que você escolher).
• Permissions (permissões): Send (enviar), Read (ler) e Manage (gerenciar). Hoje a API tem um único endpoint, o de envio de e-mail, então Send é a permissão de que seus serviços precisam.

As chaves têm o formato ibx_ seguido de 32 caracteres hexadecimais. O prefixo as torna fáceis de reconhecer e fáceis de detectar por scanners de segredos.

Regra 1: uma chave por serviço e ambiente

Não compartilhe uma única chave pela empresa inteira. Crie uma chave separada para cada serviço e para cada ambiente:

Chaves separadas significam que:

• Um vazamento fica contido. Revogar prod-billing não derruba os e-mails de login.
• Cada serviço envia do endereço certo. Uma chave vinculada ao servidor billing@ envia de billing@, e não de qualquer que tenha sido o primeiro servidor conectado. Se você excluir um servidor vinculado, a chave passa a usar o seu primeiro servidor, então vincule as chaves de novo quando remover servidores.
• A rotação é tranquila. Você pode renovar a chave de um serviço sem mexer nas outras.

Regra 2: conceda a menor permissão que funcione

Um backend que envia e-mails precisa de Send e de nada mais, então deixe Read e Manage desmarcadas. Quanto menos uma chave puder fazer, menor o custo de um vazamento.

Regra 3: chaves ficam no servidor, nunca no cliente

Tudo o que é enviado para um navegador ou um app mobile pode ser extraído, minificado ou não. Isso inclui:

• bundles JavaScript (React, Vue, client components do Next.js),
• variáveis de ambiente com prefixo para o navegador, como NEXT_PUBLIC_, VITE_ ou REACT_APP_,
• binários de apps iOS e Android.

Se uma ação do usuário no seu frontend precisa disparar um e-mail, chame um endpoint do seu próprio backend. Seu backend verifica se o usuário tem permissão para isso, aplica rate limits e só então chama a Inbixio com a chave que mantém no próprio ambiente.

// ✅ Browser → your API → Inbixio
await fetch('/api/invite', { method: 'POST', body: JSON.stringify({ email }) });

// ❌ Never do this in frontend code
fetch('https://backend.inbixio.com/api/send-email/', {
  headers: { 'X-API-Key': 'ibx_…' }, // visible to every visitor
});

Regra 4: guarde chaves como senhas

• Coloque as chaves em um gerenciador de segredos (AWS Secrets Manager, Google Secret Manager, Doppler, 1Password, Vault) ou nas variáveis de ambiente criptografadas da sua plataforma.
• Nunca faça commit delas. Adicione .env ao .gitignore e ative a varredura de segredos nos seus repositórios; o push protection do GitHub bloqueia muitos vazamentos antes que aconteçam.
• Mantenha as chaves fora dos logs. Se você registra as requisições de saída, remova antes o header X-API-Key.
• Não cole chaves em tickets, chats ou capturas de tela. Compartilhe o acesso ao segredo, não o valor dele.

Regra 5: faça rotação periódica e imediata na dúvida

A Inbixio pode renovar uma chave: clique no ícone de atualizar ao lado dela na página API Keys. A renovação gera um novo valor com o mesmo nome, acesso ao servidor e permissões, e o valor antigo deixa de funcionar na hora. Para rotacionar uma chave de produção sem nenhum envio com falha:

1. Crie uma segunda chave com as mesmas configurações (por exemplo, prod-auth-2).
2. Faça o deploy da nova chave no serviço e confirme que as requisições dela retornam 200, por exemplo nos logs da sua própria aplicação.
3. Exclua a chave antiga.

Use o ícone de atualizar quando a rapidez importar mais do que uma transição sem interrupções, como logo após um vazamento. Rotacione as chaves de rotina a cada poucos meses e sempre que alguém com acesso sair da equipe.

Se uma chave vazar

Trate como um incidente, mas um incidente administrável:

1. Renove (ícone de atualizar) ou exclua a chave imediatamente. Isso interrompe qualquer uso do valor antigo.
2. Confira os logs no painel em busca de atividade incomum: chamadas em horários estranhos ou um pico de volume. O log mostra quando as chamadas foram feitas, não qual chave as fez, então compare com os logs dos seus próprios serviços.
3. Verifique seu provedor de e-mail em busca de bounces ou reclamações de spam causados por mensagens que você não enviou.
4. Descubra como a chave vazou, seja por um commit, uma linha de log ou um bundle do frontend, e feche esse caminho.
5. Avise os usuários afetados se mensagens foram enviadas em seu nome, para que saibam que devem ignorá-las.

Checklist rápido

• Uma chave por serviço e ambiente, com nomes claros
• Chaves vinculadas ao servidor (endereço remetente) que cada serviço deve usar
• Apenas a permissão Send nos serviços que enviam e-mails
• Nenhuma chave em código de frontend, apps mobile ou repositórios
• Chaves guardadas em um gerenciador de segredos e removidas dos logs
• Uma data de rotação na agenda e um plano para vazamentos

Segurança também é o que mantém você fora da caixa de spam: mensagens enviadas por uma chave comprometida prejudicam a reputação do seu domínio. Combine este checklist com SPF, DKIM e DMARC para ter o quadro completo.