Vai al contenuto principale

​
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

1

Apri Chiavi API

Vai a Impostazioni → Account → Chiavi API.
2

Avvia la creazione

Seleziona Crea chiave API.
3

Descrivi la chiave

Inserisci un Nome chiaro e una descrizione facoltativa che identifichino il carico di lavoro, il responsabile e lo scopo.
4

Seleziona un livello

Scegli il livello adeguato al volume di richieste previsto per il carico di lavoro. I livelli disponibili vanno da Basic a Unlimited.
5

Imposta una scadenza

Facoltativamente, inserisci il numero di giorni che precedono la scadenza. Per le credenziali di produzione, preferisci durate brevi e conformi ai criteri.
6

Seleziona gli scope

Scegli almeno uno scope. Utilizza Seleziona tutto solo quando il carico di lavoro richiede legittimamente ogni scope disponibile per il tuo ruolo.
7

Crea ed esegui l'autenticazione

Seleziona Crea chiave e completa l’autenticazione avanzata quando richiesto.
8

Salva la credenziale

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

​
Alternativa: X-Api-Key

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.

​
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.
1

Prepara il sistema utilizzatore

Verifica di poter aggiornare immediatamente il servizio che utilizza la chiave e di disporre di un piano di rollback.
2

Ruota

Apri il menu delle azioni della chiave e seleziona Ruota chiave.
3

Salva la nuova chiave

Copia la credenziale appena visualizzata nel gestore di segreti.
4

Aggiorna e verifica

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

​
Guide correlate