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 richieste che consumano crediti a consumo, generano parlato e musica su larga scala e, in alcune implementazioni, accedono ad audio sensibile. 

Una chiave esposta costa denaro e può essere usata per generare contenuti con il tuo account. Può anche fornire un accesso eccessivamente ampio alle tue piattaforme, creando il rischio di fughe di dati e altri vettori di attacco. Già nel 2020, oltre il 90% degli sviluppatori usava le API in almeno un processo quotidiano. Oggi, con la diffusione dei protocolli di contesto dei modelli (MCP) e dell'IA, le API sono ovunque.

Questo articolo spiega come autenticare correttamente le API e come gestire le chiavi durante l'intero ciclo di vita: definizione dell'ambito, rotazione, controlli organizzativi, audit e risposta agli incidenti. Ti aiuterà a configurare correttamente l'autenticazione API e la gestione delle chiavi nel tuo team. Come riferimento durante la lettura, tieni aperti il riferimento sull'autenticazione e il riferimento sui token monouso.

Riepilogo

• ElevenAPI autentica ogni richiesta tramite un unico segreto, l'header xi-api-key: chiunque possieda una chiave può spendere crediti e generare audio con l'account.
• Non includere mai una chiave API a lunga durata in un browser, un'app mobile o qualsiasi altro elemento che un utente potrebbe ispezionare. Conservale su un server che controlli tu.
• I casi d'uso lato client devono autenticarsi con token monouso e di breve durata, creati lato server, mai con la chiave a lunga durata.
• Puoi ridurre l'impatto di una fuga di dati limitando le chiavi al privilegio minimo necessario, separandole per ambiente e ruotandole regolarmente.
• L'audit e il rilevamento delle 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 sia autorizzata ad agire su un account specifico prima di iniziare a operare. Chi effettua la richiesta presenta la credenziale, il servizio la verifica e, dopo la verifica, fornisce una risposta. 

In parole semplici, risponde a questa domanda: questa richiesta è autorizzata ad agire per questo account? È importante notare che questo processo è diverso dall'autorizzazione API, che definisce ciò che una richiesta autenticata può fare nel tuo sistema.

Cos'è la gestione delle chiavi?

La gestione delle chiavi comprende l'insieme più ampio di pratiche che usi per governare una chiave API durante il suo ciclo di vita. Determina come crei, archivi, usi, ruoti e revochi l'accesso alle chiavi. Questi sistemi garantiscono la sicurezza di una chiave API end-to-end. 

Con sistemi rigorosi di gestione delle chiavi, puoi prevenire l'esposizione delle chiavi e ridurre il rischio che diventino accessibili pubblicamente. 

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 quando una chiave viene gestita in modo errato. Esaminare prima il modello di minaccia fa sì che ogni pratica successiva abbia uno scopo chiaro: ciascuna riduce la probabilità che una chiave venga esposta o il danno che provoca quando accade.

ElevenAPI autentica tramite un unico meccanismo basato su un segreto: l'header xi-api-key. Chiunque possieda la chiave è autorizzato e non è previsto un secondo fattore nella richiesta stessa.

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

Possono generare contenuti su larga scala e il nostro modello di rate limiting rende la situazione più significativa di quanto sembri a prima vista. Il limite si basa sulla concorrenza, non su una semplice quota di richieste al minuto. Una chiave di un piano con un limite di concorrenza pari a cinque per una determinata famiglia di modelli può sostenere un numero rilevante di generazioni simultanee, e un attaccante che conosce questi limiti può parallelizzare l'abuso.

Possono produrre contenuti con il tuo account. Qualsiasi audio generato con la tua chiave viene attribuito al tuo workspace e, in base alle voci e agli input coinvolti, ciò può rappresentare un problema reputazionale e, talvolta, legale.

I modi in cui le chiavi vengono esposte sono banali e corrispondono alle stesse modalità di errore che espongono qualsiasi altro tipo di credenziale:

• Chiavi API nel codice lato client: una chiave inclusa in un bundle del browser, un binario mobile o una single-page app è, a tutti gli effetti, pubblica. La minificazione non è offuscamento.
• Chiavi API nei repository: chiavi hardcoded sottoposte a commit in Git, inclusi repository privati che in seguito diventano pubblici o vengono clonati ampiamente, e file come .env che non erano mai destinati al tracciamento.
• Chiavi API nei log e nelle tracce: i logger delle richieste, gli strumenti di error tracking e le pipeline di osservabilità acquisiscono abitualmente gli header HTTP. Una chiave in xi-api-key finisce nel tuo archivio di log, presso il tuo fornitore APM e nelle mani di chiunque abbia accesso in lettura a uno dei due.
• Chiavi API nella CI e negli screenshot: log di build, ticket di assistenza e terminali condivisi.

Ciascuna delle sezioni seguenti mira a ridurre la probabilità o l'impatto di una di queste situazioni.

La regola fondamentale: conserva le chiavi API lato server

Tutto il resto di questo articolo offre indicazioni per ridurre i rischi legati all'autenticazione e alla gestione delle chiavi API. Questa regola ne è il fondamento e dovresti applicarla prima di ogni altra cosa.

Poiché il meccanismo è così semplice, la regola fondamentale è che una chiave API a lunga durata deve trovarsi soltanto su un server che controlli tu. Non deve mai essere inclusa in un browser, un'app mobile, un client desktop o qualsiasi elemento che un utente possa scaricare e ispezionare. Se la chiave è nel codice lato client, considerala già compromessa.

L'SDK legge automaticamente ELEVENLABS_API_KEY, quindi il codice più pulito non passa alcun valore 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, deve essere recuperata da un secret manager (AWS Secrets Manager, GCP Secret Manager, HashiCorp Vault o l'equivalente della tua piattaforma) all'avvio del processo, non incorporata in un'immagine o in un file .env sottoposto a commit nel repository.

Token monouso per app lato client

La regola fondamentale è assoluta, ma molti casi d'uso legittimi richiedono che sia il client a raggiungere ElevenAPI: un browser che riproduce in streaming Text to Speech, un'app mobile che acquisisce audio per la trascrizione e un agente in tempo reale eseguito nella scheda dell'utente. La chiave a lunga durata non può trovarsi lì. La soluzione è fornire al client una credenziale a basso rischio in caso di esposizione: un token monouso e di breve durata.

Il tuo server conserva la chiave a lunga durata, autentica e autorizza l'utente con la tua logica di sessione, quindi crea un token di breve durata e fornisce al client soltanto quello. Il token scade rapidamente ed è limitato all'operazione per cui è stato emesso, quindi un token esposto ha poco valore e ben presto non ne ha più alcuno. Consulta il riferimento sui token monouso per gli endpoint supportati e la struttura esatta della richiesta.

Ecco la logica essenziale di un endpoint broker. Autorizza l'utente con la tua logica di sessione, quindi crea un token tramite l'endpoint tokens documentato. La richiesta parte dal server con la xi-api-key a lunga durata e al client torna soltanto il token di breve durata risultante.

// ... 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 usa quindi quel token per connettersi e la chiave a lunga durata non entra mai nella pagina.

Limitare le chiavi al privilegio minimo necessario

Il privilegio minimo necessario è il principio secondo cui ogni chiave deve avere soltanto le autorizzazioni richieste dalla sua funzione, e niente di più. ElevenAPI ti consente di applicare diverse restrizioni basate sulle autorizzazioni, che limitano ciò che una chiave può e non può fare.

Un'unica chiave onnipotente è il caso peggiore in termini di impatto e rappresenta anche l'impostazione predefinita più semplice. Un approccio migliore consiste nel presumere che prima o poi una chiave verrà esposta e assicurarsi che, quando accade, possa fare soltanto ciò che il suo compito richiede.

Inizia dalla restrizione dell'ambito, che limita gli endpoint API che una chiave può chiamare. Una chiave usata soltanto per la trascrizione non necessita dell'accesso a Text to Speech; una chiave per una funzionalità di musica non deve accedere alla gestione delle voci.

Poi c'è la quota di crediti. Assegnare un limite di crediti personalizzato per ogni chiave limita il danno economico di un'esposizione e contiene anche i loop fuori controllo nel tuo codice.

La whitelist degli IP offre un'ulteriore protezione. Puoi limitare una chiave a indirizzi IP o intervalli CIDR specifici e le richieste da IP non presenti nella whitelist vengono rifiutate con un 403. Si tratta di una funzionalità Enterprise attualmente in anteprima, disponibile tramite il tuo account manager.

Infine, non condividere una chiave tra sviluppo, staging e produzione. Emetti una chiave distinta per ogni ambiente, ciascuna con il proprio ambito e la propria quota. Le chiavi per ambiente impediscono che l'esposizione su un laptop di uno sviluppatore coinvolga i crediti di produzione, ti consentono di ruotare un ambiente senza interrompere gli altri e rendono interpretabili i log di utilizzo perché il traffico è già segmentato per origine.

Rotazione delle chiavi API

La rotazione delle chiavi è la pratica di sostituire regolarmente una chiave con una nuova. È anche un'azione da intraprendere ogni volta che sospetti una violazione o un'esposizione.

La rotazione pianificata riduce anche la finestra in cui un'esposizione non rilevata può essere sfruttata. La rotazione è indolore soltanto se il tuo codice è stato progettato per supportarla, quindi prevedila prima che diventi necessaria.

La tecnica principale consiste nella sovrapposizione delle chiavi, che consente una transizione senza downtime:

1. Genera una nuova chiave API: crea una nuova chiave accanto a quella esistente, con lo stesso ambito, la stessa quota e le stesse restrizioni IP. Ora sono entrambe valide.
2. Aggiorna la chiave: distribuisci la nuova chiave aggiornando il segreto nel tuo secret manager e permettendo alle istanze di acquisirla (con un riavvio, una nuova lettura o un aggiornamento del secret manager, a seconda della configurazione).
3. Conferma il traffico: verifica che il traffico passi attraverso la nuova chiave. Monitora l'utilizzo per confermare che la vecchia chiave non venga più usata.
4. Rimuovi l'accesso della chiave: revoca la vecchia chiave quando non mostra traffico per un intervallo di tempo sicuro.

Poiché entrambe le chiavi sono valide durante la sovrapposizione, non c'è mai un momento in cui le richieste falliscono per mancanza di una credenziale. La finestra di sovrapposizione offre un secondo vantaggio: un'istanza configurata in modo errato si rivela continuando a usare la vecchia chiave, così puoi individuarla prima di disattivarla.

Per fare in modo che la sovrapposizione non sia un evento, struttura il codice affinché la rotazione sia una modifica di configurazione, mai una modifica al codice. Leggi la chiave da un unico punto in cui possa essere aggiornata e lascia che un solo interruttore stabilisca 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 una sovrapposizione, mantieni valorizzate sia PRIMARY sia SECONDARY e modifica ELEVENLABS_KEY_ACTIVE. Il codice dell'applicazione non cambia mai.

Come cadenza, una rotazione ordinaria ogni 90 giorni è un'impostazione predefinita ragionevole per le chiavi backend; eseguila più spesso per chiavi di alto valore o ampiamente accessibili e immediatamente in caso di esposizione. Puoi automatizzarla con un job pianificato che crea, distribuisce, verifica e revoca le chiavi, trasformando la rotazione da un evento a un processo in background.

Controlli di accesso e autorizzazioni del workspace

Mentre la definizione dell'ambito e la rotazione proteggono le singole chiavi, i controlli del workspace regolano chi può crearle fin dall'inizio. Offrono uno spazio in cui definire e seguire le policy organizzative, che influenzeranno tutte le tue future pratiche di gestione delle chiavi.

Inizia separando le credenziali umane da quelle delle macchine. Le persone accedono alla dashboard con i propri account e autorizzazioni; i servizi si autenticano con chiavi o, meglio ancora, service account. Non lasciare che un servizio usi una chiave creata dall'accesso personale di un individuo e non permettere alle persone di condividere un'unica chiave macchina. Il motivo è l'offboarding: quando una persona lascia l'organizzazione o un servizio viene dismesso, devi poter revocare esattamente la credenziale giusta senza danni collaterali.

I service account perseguono lo stesso obiettivo. Assegnano ai workload delle macchine un'identità non legata a una persona, con il proprio ambito, mantenendo affidabile la traccia di audit.

Quindi associa l'accesso ai ruoli anziché ai singoli individui, uno alla volta. I workspace supportano proprio a questo scopo le autorizzazioni per gruppi e membri. Concedi il privilegio minimo che permette a ciascun gruppo di svolgere il proprio lavoro, rivedi periodicamente i membri e punta a una configurazione in cui nessuna singola credenziale, umana o macchina, possa fare più di quanto richieda il suo ruolo.

Audit e rilevamento

Nelle sezioni precedenti abbiamo illustrato come ridurre il danno causato da un'esposizione. In questa sezione spieghiamo come rilevare se un'esposizione è avvenuta. Un buon rilevamento si basa su tre abitudini. 

La prima consiste nel registrare quale chiave (tramite identificatore, mai tramite valore segreto) ha servito quale classe di richieste, da dove e con quale volume. Rimuovi l'header xi-api-key da ogni livello di logging e tracing. Una regola di redazione nel middleware HTTP e nella configurazione APM elimina il modo più comune con cui le chiavi finiscono negli archivi di log.

La seconda consiste nel monitorare il consumo di crediti per individuare anomalie. Tieni traccia nel tempo del consumo di crediti per chiave e invia un avviso in caso di deviazioni dalla baseline: un picco improvviso, generazioni in orari insoliti o una chiave che dovrebbe essere inattiva e diventa improvvisamente attiva.

La terza consiste nel monitorare gli header di concorrenza. Restituiamo le richieste concorrenti attuali e massime in ogni risposta, negli header current-concurrent-requests e maximum-concurrent-requests. Ti indicano il margine di capacità disponibile e una permanenza prolungata al massimo che non hai avviato tu è un forte segnale di abuso. L'utilizzo dell'endpoint HTTP diretto espone direttamente gli header della risposta:

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 dovrebbero attivare degli avvisi. Una dashboard che nessuno guarda non consente di rilevare nulla. Collega i segnali relativi a picchi di crediti e saturazione della concorrenza allo stesso percorso di alerting che usi per le interruzioni, con un responsabile chiaramente definito.

Risposta agli incidenti

Anche con i migliori sistemi di sicurezza e monitoraggio possibili, devi comunque presumere che prima o poi una chiave verrà esposta. Pianificare questa eventualità con un elenco di passaggi per limitare i danni ti offre una roadmap di risposta che fa risparmiare tempo e riduce l'impatto.

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

1. Revoca immediatamente la chiave esposta: non aspettare di comprendere l'intera portata. Una chiave revocata non può generare contenuti e la revoca è reversibile, nel senso che puoi sempre emettere una chiave sostitutiva. Questa è l'azione con il valore più alto.
2. Ruota a una nuova chiave: se la chiave esposta serviva il traffico di produzione, usa la procedura di sovrapposizione al contrario: crea una nuova chiave, sposta il traffico e poi conferma che la chiave esposta non sia più attiva. Poiché il tuo codice legge la chiave dalla configurazione, si tratta di una modifica della configurazione, non del codice.
3. Valuta l'impatto dai log di utilizzo: una volta contenuta l'esposizione, quantificala. Per quanto tempo la chiave è stata valida ed esposta? Quali crediti sono stati consumati durante quel periodo e il pattern corrisponde a traffico legittimo o a un abuso? Quali endpoint ha raggiunto?
4. Ruota i segreti dipendenti: una chiave raramente viene esposta da sola. Se è stata esposta in un repository, un archivio di log o una pipeline CI, considera esposti anche i segreti vicini presenti nello stesso punto e ruota anche quelli.
5. Chiudi il percorso di esposizione: individua come la chiave è stata esposta e risolvi il problema, altrimenti accadrà di nuovo: aggiungi il file a .gitignore e elimina la cronologia, aggiungi la redazione degli header al logger, rimuovi il segreto dall'artefatto di build e limita l'accesso al sistema CI.
6. Scrivi il post-mortem: documenta la cronologia, l'impatto, la causa principale e i controlli concreti aggiunti (restrizione dell'ambito, whitelist degli IP, uno scanner di segreti nella CI e una cadenza di rotazione più rapida).

Seguendo questi passaggi, avrai un processo di riferimento per gli scenari di emergenza dovuti all'esposizione delle API. 

Conformità normativa: SOC 2, HIPAA e conservazione dei dati

L'autenticazione è un elemento di una più ampia valutazione della conformità normativa ed è importante fare attenzione a ciò che si può e non si può affermare. Considera quanto segue come punto di partenza basato sui fatti, non come una valutazione per il tuo caso d'uso.

ElevenLabs è conforme a SOC 2. Per i piani e i casi d'uso idonei sono disponibili la conformità HIPAA e modalità senza conservazione dei dati. L'assenza di conservazione significa che il contenuto delle richieste non viene archiviato dopo l'elaborazione, aspetto importante quando gli input o l'audio generato sono sensibili.

L'applicabilità di una determinata modalità dipende dal tuo piano, dalla tua configurazione e dalle specifiche di ciò che elabori. Conferma l'idoneità e i termini esatti per il tuo account prima di fare affidamento su uno di questi elementi, e abbinali ai controlli di accesso descritti sopra. Le certificazioni di conformità normativa regolano il modo in cui la piattaforma gestisce i tuoi dati; la gestione delle chiavi regola chi può agire per tuo conto, e questa parte è sotto la tua responsabilità.

Come si presenta una buona sicurezza delle chiavi API

Le chiavi esclusivamente lato server eliminano la principale superficie di esposizione. I token monouso estendono questa garanzia ai client che hanno effettivamente bisogno di raggiungere la nostra API. La definizione dell'ambito e la separazione per ambiente limitano i danni di ogni singola esposizione. La rotazione integrata nella configurazione rende il ripristino un'operazione ordinaria anziché rischiosa. I controlli del workspace mantengono distinte le identità umane e quelle delle macchine. L'audit trasforma l'abuso in un avviso anziché in una sorpresa in fattura. Un runbook scritto trasforma un incidente in una procedura.

È la stessa igiene delle credenziali che protegge qualsiasi segreto di alto valore, applicata a una chiave il cui valore specifico consiste nello spendere denaro e generare audio su larga scala.

Quando sei pronto a implementare tutto questo con le strutture di richiesta reali, il riferimento sull'autenticazione e quello sui token monouso contengono l'elenco aggiornato degli endpoint supportati. Per comprendere il modello di concorrenza che il tuo monitoraggio deve seguire, le prossime letture giuste sono il riferimento sui modelli e la guida rapida API.

Proteggi la tua integrazione ElevenAPI

Una solida autenticazione API è un controllo fondamentale su cui si basano molte altre pratiche di sicurezza. Misure come l'uso di chiavi esclusivamente lato server, l'implementazione di token monouso per i client, la definizione dell'ambito secondo il privilegio minimo necessario e l'integrazione della rotazione nella gestione delle chiavi aiutano a prevenire i rischi su larga scala.

Per maggiori informazioni sugli endpoint supportati e sul formato esatto dell'header da usare, consulta la documentazione di ElevenAPI. Se sei pronto per iniziare, richiedi una chiave API di ElevenLabs per iniziare a sviluppare oggi. 

Domande frequenti sull'autenticazione API e la gestione delle chiavi