> ## Documentation Index
> Fetch the complete documentation index at: https://docs.casebender.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Chiavi API
> Crea, limita, monitora, ruota, sospendi, revoca e utilizza in modo sicuro le chiavi API di CaseBender.
## Panoramica
Le chiavi API forniscono accesso programmatico a CaseBender. Apri **Impostazioni → Account → Chiavi API** per gestire le chiavi disponibili per il tuo account e l'organizzazione corrente.
La pagina offre:
* Filtri per ricerca, stato o livello
* Identificatori delle chiavi mascherati
* Stato, livello, data dell'ultimo utilizzo e numero di richieste
* Statistiche di utilizzo
* Azioni del ciclo di vita, quali rotazione, sospensione, revoca ed eliminazione
Una chiave API è una credenziale. Conservala in un gestore di segreti approvato, non eseguirne mai il commit nel controllo del codice sorgente e non includerla mai in log, schermate, ticket o messaggi di chat.
## Prerequisiti
* Il tuo ruolo deve consentire le operazioni di scrittura e la gestione delle chiavi API.
* Gli scope disponibili vengono filtrati in base al tuo ruolo.
* La creazione, la revoca o l'eliminazione di una chiave può richiedere l'autenticazione avanzata.
* L'organizzazione può imporre criteri aggiuntivi di autenticazione e accesso.
I ruoli di sola lettura possono visualizzare le informazioni consentite, ma non modificare le chiavi.
## Creare una chiave API
Vai a **Impostazioni → Account → Chiavi API**.
Seleziona **Crea chiave API**.
Inserisci un **Nome** chiaro e una descrizione facoltativa che identifichino il carico di lavoro, il responsabile e lo scopo.
Scegli il livello adeguato al volume di richieste previsto per il carico di lavoro. I livelli disponibili vanno da **Basic** a **Unlimited**.
Facoltativamente, inserisci il numero di giorni che precedono la scadenza. Per le credenziali di produzione, preferisci durate brevi e conformi ai criteri.
Scegli almeno uno scope. Utilizza **Seleziona tutto** solo quando il carico di lavoro richiede legittimamente ogni scope disponibile per il tuo ruolo.
Seleziona **Crea chiave** e completa l'autenticazione avanzata quando richiesto.
Copia la chiave completa da **Salva la tua chiave API** in un gestore di segreti approvato prima di selezionare **Fine**.
La chiave completa viene mostrata una sola volta. CaseBender conserva esclusivamente le informazioni necessarie per convalidarla e identificarla; non è possibile recuperare successivamente la credenziale in testo normale.
## Scegliere gli scope
Gli scope utilizzano uno schema risorsa-azione, ad esempio `cases:read` o `organizations:*`. Le categorie di scope possono includere casi, avvisi, attività, utenti, team, organizzazioni, impostazioni e gestione delle chiavi API.
Segui il principio del privilegio minimo:
* Utilizza scope di sola lettura per i carichi di lavoro di reporting e ricerca.
* Concedi scope di scrittura solo quando l'integrazione esegue modifiche.
* Evita scope con caratteri jolly e amministrativi per le integrazioni con un unico scopo.
* Crea chiavi distinte per servizi o ambienti non correlati.
* Riesamina i requisiti degli scope ogni volta che un'integrazione cambia.
Il modulo di creazione nelle Impostazioni offre soltanto gli scope consentiti dal ruolo corrente. Le richieste API vengono valutate rispetto agli scope della chiave e agli altri controlli sui dati applicati.
Concedi `api-keys:write`, scope con caratteri jolly o scope amministrativi solo ad automazioni attendibili ed esplicitamente autorizzate a creare o gestire altre credenziali.
## Scegliere un livello
Il livello registra la classe di servizio prevista per una chiave. I livelli disponibili sono:
* **Basic**
* **Standard**
* **Professional**
* **Enterprise**
* **Unlimited**
I limiti effettivi relativi a richieste, operazioni in blocco e concorrenza dipendono dalla configurazione della distribuzione. Verifica con l'amministratore della piattaforma la velocità effettiva e l'applicazione dei limiti in produzione, anziché presumere che la selezione di un livello modifichi i limiti attivi o renda una chiave priva di restrizioni.
## Autenticare le richieste API
Utilizza la chiave completa con una delle intestazioni supportate per chiave singola.
### Metodo consigliato: token Bearer
```bash theme={null}
curl "https://your-instance.casebender.com/api/v1/alerts" \
--header "Authorization: Bearer $CASEBENDER_API_KEY" \
--header "Content-Type: application/json"
```
### Alternativa: X-Api-Key
```bash theme={null}
curl "https://your-instance.casebender.com/api/v1/alerts" \
--header "X-Api-Key: $CASEBENDER_API_KEY" \
--header "Content-Type: application/json"
```
Conserva la chiave in una variabile d'ambiente o in un meccanismo di inserimento dei segreti. Non incollare una chiave reale direttamente nella cronologia della shell o nel codice sorgente.
Per ulteriori esempi, consulta l'[introduzione alla documentazione di riferimento delle API](/it/api-reference/introduction).
## Comprendere gli stati delle chiavi
* Le chiavi **Attive** possono autenticare le richieste, nel rispetto dei controlli relativi a scope e criteri.
* Le chiavi **Sospese** sono temporaneamente disabilitate e possono essere riattivate.
* Le chiavi **Revocate** non sono più valide in modo permanente.
* Le chiavi **Scadute** hanno superato la scadenza configurata.
## Visualizzare le statistiche di utilizzo
Apri il menu delle azioni di una chiave e seleziona **Visualizza statistiche** per esaminare:
* Richieste totali
* Richieste riuscite
* Richieste non riuscite
* Tempo medio di risposta
* Endpoint principali
Utilizza queste statistiche per individuare credenziali inutilizzate, endpoint imprevisti e carichi di lavoro che richiedono un livello diverso.
## Ruotare una chiave
La rotazione sostituisce il segreto attuale con uno nuovo.
Verifica di poter aggiornare immediatamente il servizio che utilizza la chiave e di disporre di un piano di rollback.
Apri il menu delle azioni della chiave e seleziona **Ruota chiave**.
Copia la credenziale appena visualizzata nel gestore di segreti.
Aggiorna il carico di lavoro che utilizza la chiave, riavvialo o distribuiscilo nuovamente secondo necessità ed esegui una richiesta di prova con scope appropriato.
La rotazione invalida il segreto precedente. Coordina la modifica per evitare un'interruzione dell'integrazione.
La rotazione viene avviata dall'operatore. Un intervallo di rotazione memorizzato non garantisce, da solo, che CaseBender ruoti e distribuisca automaticamente una chiave sostitutiva.
## Sospendere o riattivare una chiave
Utilizza **Sospendi** per disabilitare temporaneamente una chiave durante un'indagine o una manutenzione pianificata. Utilizza **Riattiva** solo dopo aver verificato che la credenziale e il relativo sistema utilizzatore siano attendibili.
La sospensione è preferibile all'eliminazione quando è necessaria un'azione di contenimento reversibile.
## Revocare una chiave
Utilizza **Revoca** quando una credenziale è compromessa, non è più attendibile o viene ritirata definitivamente. La revoca può richiedere l'autenticazione avanzata e non può essere annullata.
Dopo la revoca:
1. Rimuovi il segreto da tutti i sistemi utilizzatori.
2. Esamina le statistiche di utilizzo e la telemetria di sicurezza.
3. Analizza le richieste impreviste.
4. Crea una chiave sostitutiva distinta solo se il carico di lavoro è ancora autorizzato.
## Eliminare una chiave
L'eliminazione rimuove il record della chiave e la relativa visibilità diretta nell'interfaccia di gestione. Può richiedere l'autenticazione avanzata.
Revoca una chiave prima di eliminarla quando è necessaria una sequenza chiara per il ritiro della credenziale. L'attuale menu delle azioni non presenta una finestra di conferma separata per ogni operazione distruttiva.
## Raccomandazioni di sicurezza
* Assegna un responsabile umano identificato e un responsabile del carico di lavoro.
* Utilizza chiavi distinte per produzione, staging e sviluppo.
* Imposta una scadenza conforme ai criteri per le credenziali.
* Esegui immediatamente la rotazione in caso di sospetta esposizione.
* Monitora le richieste non riuscite e gli endpoint imprevisti.
* Revoca le chiavi inutilizzate anziché lasciarle attive.
* Non inviare mai le chiavi tramite email o strumenti di collaborazione.
## Risoluzione dei problemi
### Crea chiave viene rifiutato
Inserisci un nome, seleziona almeno uno scope, verifica che il ruolo disponga dell'accesso in scrittura e completa l'eventuale richiesta di autenticazione avanzata.
### Una richiesta API restituisce 401
Verifica che la chiave attiva completa sia fornita come token Bearer o tramite `X-Api-Key` e controlla che non sia scaduta, sospesa o revocata.
### Una richiesta API restituisce 403
La chiave è stata autenticata correttamente, ma non dispone dello scope o dell'accesso ai dati richiesto. Aggiungi soltanto lo scope minimo necessario tramite un flusso autorizzato di gestione delle chiavi.
### Le richieste sono soggette a limitazione della frequenza
Riduci la frequenza delle richieste, rispetta le indicazioni sui nuovi tentativi contenute nella risposta oppure chiedi a un amministratore se il carico di lavoro richiede un altro livello.
### La chiave completa non è più visibile
Le chiavi in testo normale non possono essere recuperate. Ruota la chiave oppure creane una sostitutiva e aggiorna il sistema utilizzatore.
## Documentazione di riferimento delle API
* [Elencare le chiavi API](/en/api-reference/endpoint/api-keys/list)
* [Creare una chiave API](/en/api-reference/endpoint/api-keys/create)
* [Elencare gli scope disponibili](/en/api-reference/endpoint/api-keys/scopes)
* [Ottenere una chiave API](/en/api-reference/endpoint/api-keys/get-by-id)
* [Ruotare una chiave API](/en/api-reference/endpoint/api-keys/rotate)
* [Visualizzare le statistiche di una chiave API](/en/api-reference/endpoint/api-keys/stats)
* [Eliminare una chiave API](/en/api-reference/endpoint/api-keys/delete)
## Guide correlate
* [Introduzione alla documentazione di riferimento delle API](/it/api-reference/introduction)
* [Controllo degli accessi](/en/security/access-control)
* [Organizzazioni](./organizations.mdx)