Skip to main content
Le chiavi API autenticano le richieste alla Public API di /v1. Ogni chiave appartiene a un account di servizio e viene creata dalla pagina di dettaglio di tale account nel Developer Hub. Utilizzi una chiave API con ambito limitato per un’integrazione backend privata quando la conservazione sicura e la rotazione di un segreto soddisfano i Suoi requisiti. Non sono necessari né un client OAuth né uno scambio di token. Se la Sua organizzazione richiede invece token di accesso OAuth di breve durata, consulti Autenticazione.

​
Anatomia di una chiave

  • Identificatore — inizia con ak_. Può essere citato senza rischi in ticket, log e configurazioni; da solo non concede alcun accesso.
  • Segreto — inizia con lsk_live_. È la credenziale che la Sua integrazione presenta. Viene mostrato una sola volta, al momento della creazione o della rotazione, e non può essere recuperato in seguito. L’elenco delle chiavi mostra solo gli ultimi quattro caratteri (ad esempio lsk_live_…xQc4), in modo da poter associare una riga alla credenziale in possesso di un chiamante.
  • Autorizzazioni — un sottoinsieme delle autorizzazioni dell’account di servizio proprietario, scelto al momento della creazione. Una chiave non può mai fare più di quanto consenta il proprio account.
  • Scadenza — obbligatoria. Ogni chiave ha una data di scadenza.
Conservi i segreti in un gestore di segreti non appena vengono mostrati. Non li inserisca mai nel controllo di versione, non li incorpori nel codice lato client e non li condivida in chat. Chiunque possieda il segreto può agire con le autorizzazioni della chiave.

​
Creare una chiave

Nella pagina di dettaglio dell’account di servizio, crei una chiave seguendo quattro passaggi: assegni un nome, selezioni le autorizzazioni necessarie a questa specifica chiave, scelga una scadenza — 30, 90 o 365 giorni, oppure un periodo personalizzato fino a un anno — e verifichi il riepilogo. Il segreto viene mostrato al termine, una sola volta. Limiti l’ambito di ogni chiave al set di autorizzazioni più ristretto di cui il chiamante ha bisogno, anche quando l’account ne consente di più. Se una chiave viene compromessa, le sue autorizzazioni determinano l’entità del danno.

​
Ruotare senza interruzioni del servizio

La rotazione genera un nuovo segreto e avvia una finestra di sovrapposizione — 1 ora, 24 ore o 7 giorni — durante la quale il vecchio segreto continua a funzionare. In questo modo può distribuire il nuovo segreto nelle Sue implementazioni con i tempi che preferisce:
1

Ruotare la chiave

Scelga una finestra di sovrapposizione che copra il percorso di distribuzione più lento. Il nuovo segreto viene mostrato una sola volta: lo conservi immediatamente.
2

Aggiornare le Integrazioni

Sostituisca il vecchio segreto in ogni punto in cui è configurato. Lo stato della chiave viene mostrato come in sovrapposizione fino al termine della finestra.
3

Verificare prima della chiusura della finestra

Utilizzi i log delle richieste per verificare che il traffico sia passato al nuovo segreto. Al termine della sovrapposizione, il vecchio segreto non autentica più.
Ruoti le chiavi anche prima della scadenza: le chiavi che si avvicinano alla data di scadenza vengono contrassegnate come in scadenza nell’elenco delle chiavi. Una chiave scaduta non autentica più: le richieste effettuate con essa restituiscono un 401 con il codice credential_expired.

​
Revocare immediatamente

La revoca ha effetto immediato ed è permanente: non esiste alcuna finestra di sovrapposizione e non è possibile annullarla. Revochi una chiave non appena sospetta che il suo segreto sia stato esposto; ruoti invece la chiave quando sostituisce una credenziale integra. Le richieste effettuate con una chiave revocata restituiscono un 401 con il codice credential_revoked. Se desidera bloccare contemporaneamente tutte le chiavi in possesso di un’integrazione, disabiliti invece il relativo account di servizio.