On this page

Chiavi API

Le chiavi API sono il metodo principale per autenticarsi con l’API di Brevo. Offrono un modo semplice e sicuro per accedere al tuo account a livello programmatico.

Cosa sono le chiavi API?

Le chiavi API sono identificatori univoci che autenticano la tua applicazione quando effettua richieste all’API di Brevo. Ogni chiave è una stringa di 64 caratteri che funge sia da identificatore sia da password.

Esempio di chiave API: xkeysib-a1b2c3d4e5f6789012345678901234567890abcdef1234567890abcdef123456-Ab1Cd2Ef3Gh4

Generare chiavi API

Guida passo passo

  1. Accedi a Brevo: apri la tua dashboard Brevo
  2. Vai in Impostazioni: clicca sul tuo profilo → Impostazioni
  3. Apri Chiavi API: seleziona “Chiavi API” dal menu di sinistra
  4. Crea una nuova chiave: clicca su “Genera una nuova chiave API”
  5. Assegna un nome: dalle un nome descrittivo (ad es. “App di produzione”, “Test di sviluppo”)
  6. Imposta i permessi: scegli il livello di accesso adeguato
  7. Genera: clicca su “Genera” e copia subito la chiave

Convenzioni di nomenclatura delle chiavi API

Usa nomi descrittivi che aiutino a identificare lo scopo della chiave:

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

Tipi e permessi delle chiavi API

Chiavi ad accesso completo 

Permessi: tutti gli endpoint dell'API
Casi d'uso: integrazione applicativa completa
Livello di rischio: alto, proteggile con attenzione

Chiavi in sola lettura 

Permessi: solo richieste GET
Casi d'uso: analytics, reportistica, dashboard
Livello di rischio: basso, accesso limitato

Chiavi solo invio 

Permessi: invio di e-mail transazionali
Casi d'uso: notifiche applicative, ricevute
Livello di rischio: medio, può inviare e-mail

Chiavi per la gestione dei contatti 

Permessi: operazioni CRUD sui contatti
Casi d'uso: integrazioni CRM, invio di form
Livello di rischio: medio, modifica di dati

Usare le chiavi API

Autenticazione tramite header

Includi la tua chiave API nell’header api-key:

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

Esempi di codice

JavaScript/Node.js 

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


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


// Effettua una richiesta autenticata
apiInstance.getAccount()
  .then(data => console.log('Info account:', data))
  .catch(error => console.error('Errore:', error));

Python 

import sib_api_v3_sdk
from sib_api_v3_sdk.rest import ApiException


# Configura la chiave API
configuration = sib_api_v3_sdk.Configuration()
configuration.api_key['api-key'] = 'YOUR_API_KEY'


# Crea un'istanza dell'API
api_instance = sib_api_v3_sdk.AccountApi(sib_api_v3_sdk.ApiClient(configuration))


try:
    # Ottieni info account
    api_response = api_instance.get_account()
    print(api_response)
except ApiException as e:
    print("Eccezione durante la chiamata ad AccountApi->get_account: %s\n" % e)

PHP 

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


// Configura la chiave API
$config = SendinBlue\Client\Configuration::getDefaultConfiguration()->setApiKey('api-key', 'YOUR_API_KEY');


// Crea un'istanza dell'API
$apiInstance = new SendinBlue\Client\Api\AccountApi(
    new GuzzleHttp\Client(),
    $config
);


try {
    $result = $apiInstance->getAccount();
    print_r($result);
} catch (Exception $e) {
    echo 'Eccezione durante la chiamata ad AccountApi->getAccount: ', $e->getMessage(), PHP_EOL;
}
?>

Ruby 

require 'sib-api-v3-sdk'


# Configura la chiave API
SibApiV3Sdk.configure do |config|
  config.api_key['api-key'] = 'YOUR_API_KEY'
end


# Crea un'istanza dell'API
api_instance = SibApiV3Sdk::AccountApi.new


begin
  # Ottieni info account
  result = api_instance.get_account
  puts result
rescue SibApiV3Sdk::ApiError => e
  puts "Eccezione durante la chiamata ad AccountApi->get_account: #{e}"
end

Sicurezza delle chiavi API

Archiviazione sicura

Variabili d’ambiente (consigliato)

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


# Uso nel codice
const apiKey = process.env.BREVO_API_KEY;

Secret manager cloud

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

Best practice di sicurezza

  1. Non scrivere mai le chiavi nel codice

    // ❌ Sbagliato, in chiaro nel codice
    const apiKey = "xkeysib-a1b2c3d4...";
    

    // ✅ Giusto, variabile d'ambiente
    const apiKey = process.env.BREVO_API_KEY;

  2. Usa chiavi diverse per ogni ambiente

    Produzione:    BREVO_API_KEY_PROD
    Staging:       BREVO_API_KEY_STAGING
    Sviluppo:      BREVO_API_KEY_DEV

  3. Ruota le chiavi regolarmente

    • Imposta promemoria per la rotazione trimestrale
    • Usa strumenti di automazione per la rotazione
    • Tieni pronto un piano di rollback

  4. Monitora l’uso delle chiavi

    • Configura alert per attività anomale
    • Esamina i log di utilizzo ogni mese
    • Tieni traccia degli schemi di accesso geografico

Gestione delle chiavi

Monitoraggio delle chiavi attive

Controlla le chiavi attive nella dashboard:

Nome chiave: production-web-app
Creata: 2024-01-15
Ultimo utilizzo: 2024-01-20 14:30 UTC
Richieste oggi: 1.247
Stato: Attiva

Processo di rotazione delle chiavi

  1. Genera una nuova chiave: crea una chiave sostitutiva
  2. Aggiorna la configurazione: distribuisci con la nuova chiave
  3. Monitora: verifica che la nuova chiave funzioni correttamente
  4. Periodo di grazia: mantieni attiva la vecchia chiave per 24–48 ore
  5. Revoca la vecchia chiave: elimina la chiave precedente

Revoca di emergenza di una chiave

Se una chiave viene compromessa:

  1. Revoca immediata: elimina la chiave dalla dashboard
  2. Crea una sostituta: genera subito una nuova chiave
  3. Aggiorna le applicazioni: distribuisci la nuova chiave appena possibile
  4. Monitora l’attività: verifica eventuali utilizzi non autorizzati
  5. Report d’incidente: documenta l’incidente di sicurezza

Rate limit e chiavi API

Ogni chiave API ha limiti di richiesta individuali:

  • Piano Free: 300 richieste/giorno
  • Piano Starter: 20.000 richieste/giorno
  • Piano Business: 50.000 richieste/giorno
  • Piano Enterprise: limiti personalizzati

Header del rate limit 

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

Gestire il rate limit 

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 raggiunto. Attesa ${waitTime} secondi`);
      await new Promise(resolve => setTimeout(resolve, waitTime * 1000));


      // Riprova la richiesta
      return makeApiCall();
    }


    return response.json();
  } catch (error) {
    console.error('Chiamata API fallita:', error);
    throw error;
  }
}

Risoluzione dei problemi con le chiavi API

Messaggi di errore comuni

Chiave API non valida (401)

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

Permessi insufficienti (403)

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

Rate limit superato (429)

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

Checklist di debug

  • La chiave è formattata correttamente (64 caratteri)
  • Nessuno spazio aggiuntivo o carattere nascosto
  • La chiave ha i permessi necessari
  • La chiave è attiva (non revocata)
  • Entro i limiti di richiesta
  • Uso dell’endpoint API corretto
  • Header formattati correttamente

Prossimi passi

Assistente AI

Ciao! Chiedimi qualsiasi cosa sulla documentazione.

Inizia gratis con Brevo