On this page

Chaves API

As chaves API são o principal método de autenticação na API do Brevo. Oferecem uma forma simples e segura de aceder à tua conta de forma programática.

O que são chaves API?

As chaves API são identificadores únicos que autenticam a tua aplicação ao fazer pedidos à API do Brevo. Cada chave é uma string de 64 caracteres que serve simultaneamente como identificador e palavra-passe.

Exemplo de chave API: xkeysib-a1b2c3d4e5f6789012345678901234567890abcdef1234567890abcdef123456-Ab1Cd2Ef3Gh4

Gerar chaves API

Guia passo a passo

  1. Entra no Brevo: acede à tua dashboard do Brevo
  2. Navega até Definições: clica no teu perfil → Definições
  3. Vai a Chaves API: seleciona “Chaves API” no menu à esquerda
  4. Cria uma nova chave: clica em “Gerar uma nova chave API”
  5. Nomeia a chave: dá-lhe um nome descritivo (ex.: “App de produção”, “Testes de desenvolvimento”)
  6. Define permissões: escolhe o nível de acesso adequado
  7. Gera: clica em “Gerar” e copia a chave imediatamente

Convenções de nomes para chaves API

Usa nomes descritivos que ajudem a identificar o propósito da chave:

  • production-web-app
  • staging-environment
  • mobile-app-ios
  • webhook-listener
  • data-sync-service

Tipos e permissões de chaves API

Chaves com acesso total 

Permissões: todos os endpoints da API
Casos de uso: integração aplicacional completa
Nível de risco: elevado, protege com cuidado

Chaves apenas de leitura 

Permissões: apenas pedidos GET
Casos de uso: analytics, relatórios, dashboards
Nível de risco: baixo, acesso limitado

Chaves apenas de envio 

Permissões: envio de e-mails transacionais
Casos de uso: notificações de aplicação, recibos
Nível de risco: médio, pode enviar e-mails

Chaves para gestão de contactos 

Permissões: operações CRUD em contactos
Casos de uso: integrações de CRM, envio de formulários
Nível de risco: médio, modificação de dados

Usar chaves API

Autenticação por cabeçalho

Inclui a tua chave API no cabeçalho api-key:

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

Exemplos de código

JavaScript/Node.js 

const brevo = require('@brevo/api');


const apiInstance = new brevo.AccountApi();
apiInstance.setApiKey(brevo.AccountApiApiKeys.apiKey, process.env.BREVO_API_KEY);


// Fazer pedido autenticado
apiInstance.getAccount()
  .then(data => console.log('Informação da conta:', data))
  .catch(error => console.error('Erro:', error));

Python 

import sib_api_v3_sdk
from sib_api_v3_sdk.rest import ApiException


# Configurar a chave API
configuration = sib_api_v3_sdk.Configuration()
configuration.api_key['api-key'] = 'YOUR_API_KEY'


# Criar instância da API
api_instance = sib_api_v3_sdk.AccountApi(sib_api_v3_sdk.ApiClient(configuration))


try:
    # Obter informação da conta
    api_response = api_instance.get_account()
    print(api_response)
except ApiException as e:
    print("Exceção ao chamar AccountApi->get_account: %s\n" % e)

PHP 

<?php
require_once(__DIR__ . '/vendor/autoload.php');


// Configurar a chave API
$config = SendinBlue\Client\Configuration::getDefaultConfiguration()->setApiKey('api-key', 'YOUR_API_KEY');


// Criar instância da API
$apiInstance = new SendinBlue\Client\Api\AccountApi(
    new GuzzleHttp\Client(),
    $config
);


try {
    $result = $apiInstance->getAccount();
    print_r($result);
} catch (Exception $e) {
    echo 'Exceção ao chamar AccountApi->getAccount: ', $e->getMessage(), PHP_EOL;
}
?>

Ruby 

require 'sib-api-v3-sdk'


# Configurar a chave API
SibApiV3Sdk.configure do |config|
  config.api_key['api-key'] = 'YOUR_API_KEY'
end


# Criar instância da API
api_instance = SibApiV3Sdk::AccountApi.new


begin
  # Obter informação da conta
  result = api_instance.get_account
  puts result
rescue SibApiV3Sdk::ApiError => e
  puts "Exceção ao chamar AccountApi->get_account: #{e}"
end

Segurança das chaves API

Armazenamento seguro

Variáveis de ambiente (recomendado)

Terminal window
# Ficheiro .env
BREVO_API_KEY=xkeysib-your-api-key-here


# Utilização no código
const apiKey = process.env.BREVO_API_KEY;

Gestores de segredos na cloud

  • AWS Secrets Manager
  • Google Secret Manager
  • Azure Key Vault
  • HashiCorp Vault

Boas práticas de segurança

  1. Nunca escrevas chaves diretamente no código

    // ❌ Mau, chave fixa no código
    const apiKey = "xkeysib-a1b2c3d4...";
    

    // ✅ Bom, variável de ambiente
    const apiKey = process.env.BREVO_API_KEY;

  2. Usa chaves diferentes por ambiente

    Produção:      BREVO_API_KEY_PROD
    Staging:       BREVO_API_KEY_STAGING
    Desenvolvimento: BREVO_API_KEY_DEV

  3. Roda as chaves regularmente

    • Define lembretes para rotação trimestral
    • Usa ferramentas de automação para a rotação
    • Tem um plano de rollback pronto

  4. Monitoriza o uso das chaves

    • Configura alertas para atividade invulgar
    • Analisa os registos de uso mensalmente
    • Acompanha padrões de acesso geográfico

Gestão de chaves

Monitorização das chaves ativas

Acompanha as chaves ativas na dashboard:

Nome da chave: production-web-app
Criada: 2024-01-15
Último uso: 2024-01-20 14:30 UTC
Pedidos hoje: 1 247
Estado: Ativa

Processo de rotação de chaves

  1. Gerar nova chave: cria uma chave de substituição
  2. Atualizar a configuração: faz deploy com a nova chave
  3. Monitorizar: confirma que a nova chave funciona corretamente
  4. Período de tolerância: mantém a chave antiga ativa durante 24–48 horas
  5. Revogar a chave antiga: elimina a chave anterior

Revogação de emergência

Se uma chave for comprometida:

  1. Revogação imediata: elimina a chave na dashboard
  2. Gerar substituta: cria uma nova chave de imediato
  3. Atualizar aplicações: faz deploy com a nova chave o quanto antes
  4. Monitorizar atividade: verifica se houve uso não autorizado
  5. Relatório de incidente: documenta o incidente de segurança

Rate limiting e chaves API

Cada chave API tem limites de pedidos individuais:

  • Plano Gratuito: 300 pedidos/dia
  • Plano Starter: 20 000 pedidos/dia
  • Plano Business: 50 000 pedidos/dia
  • Plano Enterprise: limites personalizados

Cabeçalhos de rate limit 

HTTP/1.1 200 OK
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1640995200

Lidar com rate limits 

async function makeApiCall() {
  try {
    const response = await fetch(url, { headers });


    if (response.status === 429) {
      const resetTime = response.headers.get('X-RateLimit-Reset');
      const waitTime = resetTime - Math.floor(Date.now() / 1000);


      console.log(`Rate limit atingido. A aguardar ${waitTime} segundos`);
      await new Promise(resolve => setTimeout(resolve, waitTime * 1000));


      // Voltar a tentar
      return makeApiCall();
    }


    return response.json();
  } catch (error) {
    console.error('Chamada à API falhou:', error);
    throw error;
  }
}

Resolução de problemas com chaves API

Mensagens de erro comuns

Chave API inválida (401)

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

Permissões insuficientes (403)

{
  "code": "permission_denied",
  "message": "API key does not have required permissions"
}

Rate limit excedido (429)

{
  "code": "too_many_requests",
  "message": "Rate limit exceeded for API key"
}

Checklist de depuração

  • A chave está formatada corretamente (64 caracteres)
  • Sem espaços extra nem caracteres invisíveis
  • A chave tem as permissões necessárias
  • A chave está ativa (não revogada)
  • Dentro dos limites de pedidos
  • A usar o endpoint correto
  • Cabeçalhos formatados corretamente

Próximos passos

Assistente AI

Olá! Pergunte-me qualquer coisa sobre a documentação.

Comece grátis com Brevo