Chiavi API

Panoramica

Le chiavi API autenticano le tue richieste all’API di ElevenLabs e tracciano l’utilizzo rispetto alla quota del tuo workspace. Ne esistono due tipi:

• Le chiavi API utente appartengono a un singolo utente ed ereditano il suo accesso alle risorse del workspace. Sono adatte allo sviluppo personale e agli script e possono avere una scadenza, così smettono automaticamente di funzionare dopo un periodo prestabilito. Poiché sono legate a una persona, una chiave API utente è interessata se l’accesso dell’utente cambia o se lascia il workspace. La creazione di chiavi API personali richiede un posto completo.
• Le chiavi API degli account di servizio appartengono a un account di servizio anziché a un singolo utente, quindi continuano a funzionare indipendentemente dalle modifiche ai membri. Sono consigliate per sistemi backend, automazioni e carichi di lavoro in produzione. Gli account di servizio sono disponibili per i clienti con più postazioni e vengono gestiti dagli amministratori del workspace.

La tua chiave API è segreta. Non condividerla con altri né esporla nel codice lato client (browser, app). Per informazioni su come inviare la chiave con una richiesta, consulta il riferimento Autenticazione API.

Entrambi i tipi di chiave possono essere limitati in vari modi:

1. Limitazione dell’ambito: limita gli endpoint API a cui la chiave può accedere.
2. Quota di crediti: imposta un limite di crediti personalizzato per controllare l’utilizzo.
3. Allowlist IP: limita la chiave a indirizzi IP o intervalli CIDR specifici. Consulta Allowlist IP.

Scadenza delle chiavi API utente

Puoi impostare una scadenza per le chiavi API utente, così smettono automaticamente di funzionare dopo un periodo prestabilito. Questo limita il periodo in cui una chiave divulgata o dimenticata può essere utilizzata ed è adatto alla natura temporanea delle chiavi legate a un singolo utente.

Imposta una scadenza quando crei o modifichi una chiave dalle tue impostazioni delle chiavi API personali. Usa il selettore Scade dopo per scegliere un’impostazione predefinita da 15 minuti a 30 giorni, oppure lascia Mai (l’impostazione predefinita). La colonna Scade mostra quando ogni chiave cesserà di essere valida.

Una volta superata la scadenza, la chiave non autentica più le richieste e queste vengono rifiutate con un errore 401. Puoi estendere o rimuovere la scadenza modificando la chiave prima che scada; altrimenti, ruotala creando una nuova chiave.

Rotazione delle chiavi API

La rotazione segue lo stesso schema in entrambi i casi: crea una nuova chiave, aggiorna le tue applicazioni per usarla, quindi elimina quella vecchia.

Le chiavi API utente vengono ruotate dalla dashboard. Apri le tue impostazioni delle chiavi API personali, crea una nuova chiave ed elimina quella vecchia dopo aver effettuato il passaggio.

Le chiavi API degli account di servizio possono essere ruotate dalla dashboard o tramite l’API:

• Nella dashboard, fai clic sull’icona del tuo profilo nell’angolo in alto a destra, seleziona Impostazioni del workspace e apri la scheda Account di servizio. Crea una nuova chiave per lo stesso account di servizio, quindi elimina quella vecchia dopo aver effettuato il passaggio.
• Tramite l’API, crea una nuova chiave per lo stesso account di servizio, quindi elimina quella vecchia.

Allowlist IP

Puoi limitare una chiave API affinché funzioni solo da indirizzi IP o intervalli CIDR specifici. Le richieste effettuate da qualsiasi altro IP verranno rifiutate con un errore 403.

Formati supportati

• Singoli indirizzi IPv4 (ad es. 203.0.113.10)
• Singoli indirizzi IPv6 (ad es. 2001:db8::1)
• Intervalli CIDR (ad es. 203.0.113.0/24)

Puoi aggiungere da 1 a 100 voci per chiave API. Gli indirizzi IP senza prefisso vengono automaticamente normalizzati a /32 (IPv4) o /128 (IPv6).

Rilevare le chiavi divulgate

ElevenLabs partecipa al programma per partner di scansione dei segreti di GitHub. Se una chiave API di ElevenLabs viene salvata in un repository GitHub pubblico, GitHub avvisa ElevenLabs e la chiave viene automaticamente disabilitata per impedire utilizzi non autorizzati.

Una chiave disabilitata in questo modo riporta exposed_publicly come disable_reason. Per ripristinare l’accesso, ruota la chiave e aggiorna le tue applicazioni affinché utilizzino quella nuova.

Disabilitare autonomamente una chiave

Se ritieni che una chiave sia stata compromessa, chi la possiede può disabilitarla direttamente tramite l’endpoint Disabilita chiave API. Chiamalo con il parametro query api_key_name=self, richiesto come conferma esplicita che intendi disabilitare la chiave usata per autenticare la richiesta.

Controllare chi può disabilitare le chiavi

L’impostazione third_party_disable_allowed controlla se una chiave può essere disabilitata da chi la possiede, tramite l’endpoint di autodisabilitazione oppure automaticamente quando viene divulgata pubblicamente. Per impostazione predefinita, è abilitata per i piani non Enterprise e disabilitata per i piani Enterprise.

Per chiave: imposta third_party_disable_allowed quando crei o aggiorni una chiave API di un account di servizio. Omettila per usare l’impostazione predefinita del workspace oppure passa clear durante l’aggiornamento per reimpostare una singola chiave al valore predefinito del workspace.

Per l’intero workspace: gli amministratori del workspace possono sovrascrivere contemporaneamente l’impostazione di ogni chiave usando l’endpoint Imposta il criterio del workspace per la disabilitazione da parte di terzi:

• true consente che ogni chiave nel workspace venga disabilitata da chi la possiede.
• false lo impedisce per ogni chiave.
• null rimuove la sovrascrittura a livello di workspace, quindi vengono nuovamente applicati il valore di ogni chiave e l’impostazione predefinita del piano.