Configuração de autenticação

Brevo oferece dois métodos de autenticação dependendo do seu caso de uso: autenticação por chave de API para acesso padrão à API e autenticação por token MCP para integrações de IA. Este guia cobre ambos os métodos.

Autenticação por chave de API

As chaves de API Brevo são usadas para acesso REST API padrão a todos os serviços Brevo.

Gerar sua chave de API

Faça login no seu painel Brevo
Navegue até Configurações → Chaves de API
Clique em Gerar uma nova chave de API
Dê à sua chave um nome descritivo (ex: “Meu App Produção”)
Copie e armazene a chave com segurança (você não a verá novamente!)

Boas práticas de segurança para chaves de API

Não recomendado

Nunca commite chaves no controle de versão
Não codifique chaves diretamente na aplicação
Não compartilhe chaves por e-mail ou chat
Não use chaves de produção para testes

Variáveis de ambiente

Armazene suas chaves de API como variáveis de ambiente:

Linux/macOS (.bashrc ou .zshrc)

export BREVO_API_KEY="your_api_key_here"

Windows (Prompt de comando)

set BREVO_API_KEY=your_api_key_here

Node.js (arquivo .env)

BREVO_API_KEY=your_api_key_here

// Carregar do ambiente
const apiKey = process.env.BREVO_API_KEY;

Python

import os

api_key = os.getenv('BREVO_API_KEY')

PHP

$apiKey = $_ENV['BREVO_API_KEY'];
// ou
$apiKey = getenv('BREVO_API_KEY');

Cabeçalhos de autenticação

Inclua sua chave de API nos cabeçalhos da requisição:

Formato de cabeçalho padrão

GET /v3/account HTTP/1.1
Host: api.brevo.com
Accept: application/json
api-key: your_api_key_here

Exemplo JavaScript

const headers = {
  'Accept': 'application/json',
  'api-key': process.env.BREVO_API_KEY
};

fetch('https://api.brevo.com/v3/account', { headers })
  .then(response => response.json())
  .then(data => console.log(data));

Python Requests

import requests

headers = {
    'Accept': 'application/json',
    'api-key': os.getenv('BREVO_API_KEY')
}

response = requests.get('https://api.brevo.com/v3/account', headers=headers)

Permissões e escopos das chaves

Diferentes chaves de API podem ter diferentes permissões:

Somente leitura: Apenas requisições GET permitidas
Envio de e-mails: Permissões para e-mails transacionais
Gestão de contatos: Criar, atualizar, excluir contatos
Gestão de campanhas: Criar e enviar campanhas
Acesso completo: Todos os endpoints da API

Testar sua autenticação

Use este endpoint para verificar se sua autenticação funciona:

curl -X GET "https://api.brevo.com/v3/account" \
  -H "Accept: application/json" \
  -H "api-key: $BREVO_API_KEY"

Resposta de sucesso (200 OK):

{
  "email": "[email protected]",
  "firstName": "John",
  "lastName": "Doe"
}

Erro de autenticação (401 Unauthorized):

{
  "code": "unauthorized",
  "message": "Invalid API key provided"
}

Rotação de chaves

Para fazer rotação da sua chave de API:

Gere uma nova chave no painel
Atualize suas variáveis de ambiente com a nova chave
Faça deploy da sua aplicação com a nova chave
Teste minuciosamente para garantir que tudo funciona
Revogue a chave antiga assim que estiver confiante com a nova

Monitoramento do uso de chaves de API

Acompanhe o uso das suas chaves de API no painel Brevo:

Requisições por dia/mês
Taxas de erro por endpoint
Padrões de uso geográfico
Horários de pico

Estratégia multi-chave

Para aplicações maiores, considere usar múltiplas chaves de API:

Produção: Dados de clientes e e-mails ao vivo
Staging: Testes de pré-produção
Desenvolvimento: Desenvolvimento local e testes
Monitoramento: Verificações de saúde e métricas
Terceiros: Integrações externas

Autenticação por token MCP

O Brevo Model Context Protocol (MCP) é um framework de integração de IA que permite que assistentes de IA interajam com os serviços Brevo. MCP usa um método de autenticação separado via tokens MCP.

O que é MCP?

MCP fornece acesso de IA padronizado às APIs Brevo através de:

Transporte: HTTPS
URL base: https://mcp.brevo.com/v1/
Formato de resposta: JSON
Autenticação: Token MCP (diferente das chaves de API)

Gerar seu token MCP

Faça login no seu painel Brevo
Navegue até Configurações → Tokens MCP (ou configurações da conta)
Gere um novo token MCP
Copie e armazene o token com segurança

Nota: MCP está atualmente disponível apenas para usuários em acesso antecipado.

Usando tokens MCP

Tokens MCP são usados especificamente para integrações de IA e conexões Model Context Protocol:

export BREVO_MCP_TOKEN="your_mcp_token_here"

Inclua o token MCP nas requisições aos endpoints MCP:

GET /v1/account HTTP/1.1
Host: mcp.brevo.com
Accept: application/json
Authorization: Bearer your_mcp_token_here

MCP vs Chave de API

Característica	Chave de API	Token MCP
Caso de uso	Acesso REST API padrão	Integração IA & conexões MCP
URL base	api.brevo.com	mcp.brevo.com
Cabeçalho	`api-key`	`Authorization: Bearer`
Disponibilidade	Todos os usuários	Usuários em acesso antecipado

Boas práticas de segurança MCP

Armazene tokens MCP separadamente das chaves de API
Use variáveis de ambiente para armazenamento de tokens
Faça rotação dos tokens regularmente
Nunca commite tokens no controle de versão
Monitore o uso MCP no seu painel

Solução de problemas de autenticação

Problemas comuns com chaves de API

Formato de chave de API inválido

As chaves devem ter exatamente 64 caracteres
Verifique espaços ou caracteres extras

Erro de permissões

Verifique se sua chave tem as permissões necessárias
Verifique se a chave está ativa no seu painel

Limite de taxa

Falhas de autenticação contam para os limites de taxa
Aguarde antes de tentar novamente com as credenciais corretas

Restrições geográficas

Algumas contas têm restrições de IP
Entre em contato com o suporte se precisar liberar IPs

Problemas comuns com tokens MCP

MCP não disponível

Certifique-se de ter acesso antecipado às funcionalidades MCP
Entre em contato com o suporte Brevo para solicitar acesso

Token inválido

Verifique se o token foi copiado corretamente sem espaços
Verifique se o token não expirou ou foi revogado

URL base incorreta

Tokens MCP funcionam apenas com mcp.brevo.com
Não use tokens MCP com endpoints api.brevo.com