Autenticazione API e gestione delle chiavi per ElevenAPI

L'autenticazione API è il modo in cui un servizio verifica che una richiesta in arrivo sia autorizzata ad agire su un account. Ad esempio, con ElevenAPI, le credenziali API autorizzano le richieste che consumano crediti a consumo, generano parlato e musica su larga scala e, in alcune implementazioni, gestiscono audio sensibili.

Una chiave trapelata comporta costi e può essere usata per generare contenuti a nome del tuo account. Potrebbe anche dare accesso eccessivo alle tue piattaforme, con il rischio di fughe di dati e altri vettori di attacco. Già nel 2020, oltre il 90% degli sviluppatori usava API almeno in un processo quotidiano. Ora, con la crescita dei protocolli MCP e dell’uso dell’IA, le API sono ovunque.

In questo articolo vediamo come autenticare correttamente le API e come gestire le chiavi durante tutto il loro ciclo di vita: definizione degli ambiti, rotazione, controlli organizzativi, auditing e risposta agli incidenti. Ti aiuterà a impostare correttamente autenticazione e gestione delle chiavi API nel tuo team. Per riferimento durante la lettura, tieni aperti il riferimento sull'autenticazione e il riferimento sui token monouso.

In breve

• ElevenAPI autentica ogni richiesta tramite un unico segreto, l’header xi-api-key: chiunque abbia una chiave può spendere crediti e generare audio sull’account.
• Non inserire mai una chiave API a lunga durata in un browser, un’app mobile o qualsiasi artefatto che un utente può ispezionare. Tienila solo su un server che controlli.
• Per i casi d’uso lato client, l’autenticazione deve avvenire con token monouso e a breve durata generati lato server, mai con la chiave a lunga durata.
• Puoi ridurre l’impatto di una fuga limitando le chiavi ai permessi minimi necessari, separando le chiavi per ambiente e ruotandole regolarmente.
• Audit e rilevamento anomalie aiutano a prevenire fughe di chiavi e sorprese.

Cos’è l’autenticazione API?

L’autenticazione API è il modo in cui un servizio conferma che una richiesta in arrivo è autorizzata ad agire su uno specifico account prima di eseguire qualsiasi operazione. Chi effettua la richiesta presenta la credenziale, il servizio la verifica e, se valida, risponde.

In pratica, risponde alla domanda: questa richiesta è autorizzata ad agire per questo account? È importante notare che questo processo è diverso dall’autorizzazione API, che definisce cosa può fare una richiesta autenticata all’interno del tuo sistema.

Cos’è la gestione delle chiavi?

La gestione delle chiavi riguarda tutte le pratiche che usi per governare una chiave API durante il suo ciclo di vita. Definisce come crei, conservi, usi, ruoti e revochi l’accesso alle chiavi. Questi sistemi servono a garantire la sicurezza di una chiave API dall’inizio alla fine.

Con sistemi rigorosi di gestione delle chiavi puoi prevenire fughe e ridurre il rischio che diventino pubbliche.

Perché la sicurezza delle chiavi API è importante: il modello di minaccia

Ora che abbiamo definito autenticazione e gestione delle chiavi, è utile essere precisi su cosa può andare storto se una chiave viene gestita male. Analizzare prima il modello di minaccia dà uno scopo chiaro a ogni pratica che vedremo: ognuna riduce la probabilità che una chiave trapeli o i danni che può causare.

ElevenAPI autentica tramite un unico meccanismo segreto: l’header xi-api-key. Chiunque abbia la chiave è autorizzato e non c’è un secondo fattore sulla richiesta.

Con la tua chiave possono spendere i tuoi crediti. Text to Speech, Speech to Text, musica ed effetti sonori sono tutti a consumo, e un attaccante con una chiave valida può generare continuamente finché la quota o il saldo non si esauriscono.

Possono generare su larga scala, e il nostro modello di rate-limiting rende la situazione più seria di quanto sembri. Il limite si basa sulla concorrenza, non su una semplice quota di richieste al minuto. Una chiave su un piano con limite di 5 concorrenze per una famiglia di modelli può sostenere molte generazioni simultanee, e un attaccante che conosce questi limiti può parallelizzare l’abuso.

Possono produrre contenuti a nome del tuo account. Qualsiasi audio generato con la tua chiave viene attribuito al tuo workspace e, a seconda delle voci e degli input usati, può essere un problema di reputazione o, a volte, legale.

Le modalità con cui le chiavi trapelano sono banali e sono le stesse che causano la fuga di qualsiasi altra credenziale:

• Chiavi API nel codice lato client: Una chiave inserita in un bundle browser, un binario mobile o una single-page app è, di fatto, pubblica. La minificazione non è offuscamento.
• Chiavi API nei repository: Chiavi hardcoded committate su Git, anche in repo private che poi diventano pubbliche o vengono clonate, inclusi file come .env che non dovevano essere tracciati.
• Chiavi API in log e trace: Logger di richieste, tracker di errori e pipeline di osservabilità spesso catturano gli header HTTP. Una chiave in xi-api-key finisce nei tuoi log, nel tuo fornitore APM e in chiunque abbia accesso in lettura.
• Chiavi API in CI e screenshot: Log di build, ticket di supporto e terminali condivisi.

Ogni sezione qui sotto serve a ridurre la probabilità o l’impatto di uno di questi scenari.

La regola fondamentale: tieni le chiavi API lato server

Tutto il resto in questo articolo serve a ridurre i rischi di autenticazione e gestione delle chiavi API. Questa regola è la base di tutto e va sempre applicata.

Poiché il meccanismo è così semplice, la regola fondamentale è che una chiave API a lunga durata deve stare solo su un server che controlli. Non deve mai essere inserita in un browser, un’app mobile, un client desktop o qualsiasi artefatto scaricabile e ispezionabile dall’utente. Se la chiave è nel codice lato client, considerala già compromessa.

L’SDK legge automaticamente ELEVENLABS_API_KEY, quindi il codice più pulito non passa nulla e inizializza il client una sola volta.

import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";

// Reads process.env.ELEVENLABS_API_KEY when apiKey is omitted - never a literal.
const elevenlabs = new ElevenLabsClient();

const audio = await elevenlabs.textToSpeech.convert("JBFqnCBsd6RMkjVDRZzb", {
  text: "Generated entirely server-side.",
  modelId: "eleven_flash_v2_5",
  outputFormat: "mp3_44100_128",
});

In produzione, la chiave dovrebbe essere recuperata da un secret manager (AWS Secrets Manager, GCP Secret Manager, HashiCorp Vault o equivalente della tua piattaforma) all’avvio del processo, non inserita in un’immagine o in un file .env committato nel repo.

Token monouso per app lato client

La regola fondamentale è assoluta, ma molti casi d’uso legittimi richiedono che il client acceda direttamente a ElevenAPI: un browser che riproduce Text to Speech in streaming, un’app mobile che registra audio per la trascrizione, un agente in tempo reale nella scheda dell’utente. La chiave a lunga durata non può essere usata qui. La soluzione è fornire al client una credenziale a basso rischio in caso di fuga: un token monouso e a breve durata.

Il tuo server conserva la chiave a lunga durata, autentica e autorizza l’utente con la tua logica di sessione, poi genera un token a breve durata e consegna solo quello al client. Il token scade rapidamente ed è limitato all’operazione per cui è stato emesso, quindi una fuga vale poco e presto nulla. Consulta il riferimento sui token monouso per gli endpoint supportati e il formato esatto della richiesta.

Ecco la logica essenziale di un endpoint broker. Autorizza l’utente con la tua logica di sessione, poi genera un token tramite l’endpoint documentato. La richiesta parte con la xi-api-key a lunga durata dal server, e solo il token a breve durata torna al client.

// ... express app and route boilerplate
app.post("/api/voice-token", async (req, res) => {
  // 1. Authorize the user with YOUR session/auth system first.
  if (!req.session?.user) return res.status(401).json({ error: "unauthorized" });

  // 2. Mint a short-lived token server-side. The long-lived key travels only
  //    in this server-to-server request, never to the browser.
  const response = await fetch("https://api.elevenlabs.io/v1/tokens", {
    method: "POST",
    headers: {
      "xi-api-key": process.env.ELEVENLABS_API_KEY as string,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({}), // populate per the tokens reference
  });

  // 3. Return only the short-lived token. The API key never leaves the server.
  res.json({ token: await response.json() });
});

Il browser poi usa quel token per connettersi, e la chiave a lunga durata non entra mai nella pagina.

Limitare le chiavi ai permessi minimi necessari

Il principio del minimo privilegio prevede che ogni chiave abbia solo i permessi necessari al suo compito, e niente di più. ElevenAPI ti permette di applicare diverse restrizioni basate sui permessi che definiscono cosa può o non può fare una chiave.

Una singola chiave onnipotente è il caso peggiore per l’impatto di una fuga, ed è anche la scelta più facile. Meglio invece presumere che prima o poi una chiave trapelerà e assicurarsi che, quando succede, possa fare solo ciò che serve.

Inizia limitando l’ambito, cioè quali endpoint API una chiave può chiamare. Una chiave usata solo per la trascrizione non ha bisogno dell’accesso a Text to Speech; una chiave per la musica non deve gestire le voci.

Poi imposta una quota di crediti. Assegnare un limite personalizzato per chiave limita i danni economici di una fuga e contiene eventuali loop nel tuo codice.

La whitelist di IP va oltre. Puoi limitare una chiave a specifici indirizzi IP o intervalli CIDR, e le richieste da IP non autorizzati vengono rifiutate con errore 403. Questa è una funzione Enterprise attualmente in anteprima, disponibile tramite il tuo account manager.

Infine, non condividere una chiave tra sviluppo, staging e produzione. Crea una chiave distinta per ogni ambiente, ognuna con il proprio ambito e quota. Le chiavi per ambiente tengono una fuga dal laptop di uno sviluppatore lontana dai crediti di produzione, ti permettono di ruotare un ambiente senza toccare gli altri e rendono i log di utilizzo più chiari perché il traffico è già segmentato per origine.

Rotazione delle chiavi API

La rotazione delle chiavi consiste nel sostituire regolarmente una chiave con una nuova. È anche un’azione da fare ogni volta che sospetti una violazione o un’esposizione.

Se fatta a intervalli regolari, la rotazione riduce la finestra in cui una fuga non rilevata può essere sfruttata. La rotazione è indolore solo se il tuo codice è progettato per gestirla, quindi pensa alla rotazione prima di averne bisogno.

La tecnica principale è l’overlap delle chiavi, che ti permette di cambiare senza downtime:

1. Genera una nuova chiave API: Aggiungi una nuova chiave insieme a quella esistente, con stesso ambito, quota e restrizioni IP. Ora sono entrambe valide.
2. Aggiorna la chiave: Distribuisci la nuova chiave aggiornando il segreto nel secret manager e lascia che le istanze la rilevino (riavvio, rilettura o refresh del secret manager, a seconda della configurazione).
3. Conferma il traffico: Verifica che il traffico passi sulla nuova chiave. Controlla che la vecchia chiave non venga più usata.
4. Rimuovi l’accesso alla chiave: Revoca la vecchia chiave quando non mostra traffico per un intervallo di sicurezza.

Poiché entrambe le chiavi sono valide durante l’overlap, non c’è mai un momento in cui le richieste falliscono per mancanza di credenziali. L’overlap ha anche un secondo vantaggio: un’istanza mal configurata si rivela continuando a usare la vecchia chiave, così puoi individuarla prima di tagliarla.

Per rendere l’overlap un non-evento, struttura il codice in modo che la rotazione sia un cambio di configurazione e mai di codice. Leggi la chiave da un solo punto, dove può essere aggiornata, e lascia che un solo switch decida quale segreto è attivo.

// Rotation is driven by configuration, not code edits. The secret manager (or
// the deploy that injects env vars) is the single point of change.
// ELEVENLABS_KEY_ACTIVE selects which slot is live, enabling overlap.
let client: ElevenLabsClient | undefined;

function activeKey(): string {
  const slot = process.env.ELEVENLABS_KEY_ACTIVE ?? "primary";
  const name = slot === "primary" ? "ELEVENLABS_API_KEY_PRIMARY" : "ELEVENLABS_API_KEY_SECONDARY";
  return process.env[name] as string;
}

function getClient(): ElevenLabsClient {
  return (client ??= new ElevenLabsClient({ apiKey: activeKey() }));
}

// Call after a secret refresh to pick up the rotated key without a deploy.
function resetClient(): void {
  client = undefined;
}

Durante l’overlap, tieni sia PRIMARY che SECONDARY valorizzate e cambia ELEVENLABS_KEY_ACTIVE. Il codice dell’applicazione non cambia mai.

Come frequenza, una rotazione ogni 90 giorni è un buon default per le chiavi backend, più spesso per chiavi di alto valore o molto usate, e subito in caso di esposizione. Puoi automatizzare il tutto con un job schedulato che crea, aggiorna, verifica e revoca, trasformando la rotazione in un processo di background.

Controlli di accesso e permessi del workspace

Mentre ambiti e rotazione proteggono le singole chiavi, i controlli del workspace regolano chi può crearle. Qui puoi definire e seguire la policy organizzativa, che influenzerà tutte le pratiche di gestione delle chiavi in futuro.

Inizia separando le credenziali umane da quelle di macchina. Le persone accedono alla dashboard con il proprio account e permessi; i servizi si autenticano con chiavi o, meglio, account di servizio. Non far girare un servizio con una chiave creata da un accesso personale e non far condividere una chiave di macchina tra più persone. Il motivo è l’offboarding: quando una persona lascia o un servizio viene dismesso, vuoi revocare solo la credenziale giusta senza danni collaterali.

Gli account di servizio servono allo stesso scopo. Danno ai workload di macchina un’identità non legata a una persona, con i propri ambiti, mantenendo l’audit trail corretto.

Poi mappa l’accesso ai ruoli invece che ai singoli utenti. I workspace supportano permessi per gruppi e membri proprio per questo. Concedi il minimo privilegio necessario a ogni gruppo, rivedi periodicamente i membri e punta a una situazione in cui nessuna credenziale, umana o di macchina, possa fare più di quanto richiesto dal suo ruolo.

Audit e rilevamento

Nelle fasi precedenti abbiamo visto come ridurre i danni di una fuga. Ora vediamo come rilevare se una fuga è avvenuta. Una buona rilevazione si basa su tre abitudini.

La prima è registrare quale chiave (tramite identificativo, mai il valore segreto) ha servito quale classe di richiesta, da dove e con che volume. Rimuovi l’header xi-api-key da ogni livello di logging e tracing. Una regola di redazione nell’HTTP middleware e nella configurazione APM elimina il modo più comune in cui le chiavi finiscono nei log.

La seconda è monitorare il consumo di crediti per anomalie. Tieni traccia del consumo per chiave nel tempo e imposta alert su deviazioni dalla norma: picchi improvvisi, generazione in orari insoliti o una chiave che dovrebbe essere inattiva ma diventa attiva.

La terza è controllare gli header di concorrenza. In ogni risposta restituiamo le richieste concorrenti attuali e massime negli header current-concurrent-requests e maximum-concurrent-requests. Ti dicono quanto margine hai, e un valore costantemente al massimo che non hai avviato tu è un forte segnale di abuso. Usando l’endpoint HTTP raw vedi direttamente questi header:

const resp = await fetch("https://api.elevenlabs.io/v1/text-to-speech/JBFqnCBsd6RMkjVDRZzb", {
  method: "POST",
  headers: {
    "xi-api-key": process.env.ELEVENLABS_API_KEY as string,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ text: "Monitoring headroom.", model_id: "eleven_flash_v2_5" }),
});

const current = resp.headers.get("current-concurrent-requests");
const maximum = resp.headers.get("maximum-concurrent-requests");
// Emit these to your metrics pipeline; alert on sustained saturation you did not cause.

Questi eventi devono generare alert. Una dashboard che nessuno guarda non rileva nulla. Collega i segnali di picco crediti e saturazione concorrenza allo stesso percorso di alert che usi per i down, con un responsabile chiaro.

Risposta agli incidenti

Anche con i migliori sistemi di sicurezza e monitoraggio, devi comunque presumere che prima o poi una chiave trapelerà. Pianificare in anticipo i passi per limitare i danni ti dà una roadmap di risposta che fa risparmiare tempo e riduce l’impatto.

Ecco un percorso predefinito di risposta agli incidenti per l’esposizione di una chiave API:

1. Revoca subito la chiave trapelata: Non aspettare di capire tutto il contesto. Una chiave revocata non può generare, e la revoca è reversibile perché puoi sempre emettere una sostituta. Questa è l’azione più importante.
2. Ruota con una nuova chiave: Se la chiave trapelata serviva traffico di produzione, usa la procedura di overlap al contrario: crea una nuova chiave, sposta il traffico, poi verifica che la chiave compromessa sia inattiva. Poiché il codice legge la chiave dalla configurazione, basta cambiare la config, non il codice.
3. Valuta l’impatto dai log di utilizzo: Una volta contenuta la fuga, quantificala. Per quanto tempo la chiave è stata valida ed esposta? Quali crediti sono stati consumati e il pattern corrisponde a traffico legittimo o abuso? Quali endpoint sono stati toccati?
4. Ruota i segreti collegati: Una chiave raramente trapela da sola. Se è stata esposta in un repo, log o pipeline CI, considera compromessi anche i segreti vicini e ruota anche quelli.
5. Chiudi la via di fuga: Trova come la chiave è uscita e correggi, altrimenti succederà di nuovo: aggiungi il file a .gitignore e cancella la cronologia, aggiungi la redazione degli header al logger, sposta il segreto fuori dall’artefatto di build e restringi l’accesso al sistema CI.
6. Scrivi il post-mortem: Documenta la timeline, l’impatto, la causa principale e i controlli aggiunti (ambiti più stretti, whitelist IP, scanner di segreti in CI, rotazione più frequente).

Seguendo questi passi avrai un processo pronto per gestire scenari di esposizione delle API.

Conformità: SOC 2, HIPAA e conservazione dei dati

L’autenticazione è solo uno degli elementi di una valutazione più ampia della conformità, quindi è importante essere precisi su cosa si può o non si può affermare qui. Considera quanto segue come punto di partenza, non come valutazione definitiva per il tuo caso.

ElevenLabs è conforme SOC 2. Per i piani e i casi d’uso idonei, sono disponibili la conformità HIPAA e le modalità zero-retention. Zero-retention significa che il contenuto della richiesta non viene conservato dopo l’elaborazione, fondamentale se i tuoi input o l’audio generato sono sensibili.

Se una modalità è applicabile dipende dal tuo piano, dalla configurazione e da cosa stai processando. Verifica l’idoneità e i termini esatti per il tuo account prima di affidarti a queste opzioni, e abbinale ai controlli di accesso descritti sopra. Le certificazioni di conformità regolano come la piattaforma gestisce i tuoi dati; la gestione delle chiavi stabilisce chi può agire per tuo conto, e questa parte è sotto il tuo controllo.

Come si presenta una buona sicurezza delle chiavi API

Le chiavi solo lato server eliminano la principale superficie di fuga. I token monouso estendono questa garanzia ai client che devono davvero accedere alla nostra API. Ambiti e separazione per ambiente limitano i danni di una singola fuga. La rotazione integrata nella configurazione rende il recupero una routine e non un rischio. I controlli del workspace distinguono tra identità umane e di macchina. L’auditing trasforma un abuso in un alert invece che in una sorpresa in fattura. Una runbook scritta trasforma un incidente in una procedura.

Sono le stesse buone pratiche che proteggono qualsiasi segreto di valore, applicate a una chiave che ha la particolarità di spendere soldi e generare audio su larga scala.

Quando sei pronto a implementare tutto sulle richieste reali, il riferimento sull’autenticazione e quello sui token monouso contengono la lista aggiornata degli endpoint supportati. Per capire il modello di concorrenza da monitorare, consulta il riferimento sui modelli e la guida rapida API.

Proteggi la tua integrazione con ElevenAPI

Una forte autenticazione API è il controllo di base su cui si costruiscono molte altre pratiche di sicurezza. Usare chiavi solo lato server, token monouso per i client, ambiti minimi e rotazione integrata nella gestione delle chiavi aiuta a prevenire rischi su larga scala.

Per maggiori informazioni sugli endpoint supportati e il formato esatto dell’header da usare, consulta la documentazione ElevenAPI. Se vuoi iniziare subito, richiedi una chiave API da ElevenLabs e inizia a costruire oggi stesso.

Domande frequenti su autenticazione API e gestione delle chiavi