# Chiavi API Utilizza le chiavi API per autenticare le richieste API. Stripe autentica le richieste API utilizzando le chiavi API del tuo account. Se una richiesta non include una chiave valida, Stripe restituisce un [errore di richiesta non valida](https://docs.stripe.com/error-handling.md#invalid-request-errors). Se una richiesta include una chiave eliminata o scaduta, Stripe restituisce un [errore di autenticazione](https://docs.stripe.com/error-handling.md#authentication-errors). Utilizza la [Dashboard per sviluppatori](https://dashboard.stripe.com/test/apikeys) per creare, rivelare, eliminare e sostituire le chiavi API. Puoi accedere alle chiavi API nella scheda [Chiavi API](https://dashboard.stripe.com/test/apikeys). > #### Se sei un nuovo utente di Stripe > > - **Proteggi la tua attività:** leggi le nostre [best practice](https://docs.stripe.com/keys-best-practices.md) per la gestione delle chiavi. - **Creazione e test**: utilizza le tue *chiavi sandbox (modalità di test)*. Le chiavi sandbox iniziano con `pk_test_` (pubblicabile), `rk_test_` (con limitazioni), e `sk_test_` (segreta). Ti consentono di effettuare dei test senza influire sui dati effettivi. - **Quando è tutto pronto per accettare pagamenti reali?** Passa alle tue **chiavi in modalità live**, che iniziano con `pk_live_`, `rk_live_` e `sk_live_`. Per istruzioni, consulta [Passaggio alla modalità live](https://docs.stripe.com/keys.md#switch-to-live-mode). - **Se hai bisogno di una chiave privata di firma webhook**: le chiavi private webhook sono separate dalle chiavi API. Le trovi nella sezione [Webhook](https://dashboard.stripe.com/webhooks) della Dashboard sotto ogni endpoint webhook. ## Tipi di chiave Quando ti registri per un account Stripe, creiamo tre tipi di chiavi API per te: | Tipo | Sicuro da esporre | Descrizione | | ------------------------------------------ | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Chiave API con limitazioni (RAK)`rk_...` | No | Chiave API con autorizzazioni gestite da te. Riduci al minimo i danni che un malintenzionato potrebbe causare alla tua attività se entrasse in possesso della tua chiave. Crea tutte le chiavi RAK che desideri e assegnale a diverse parti della tua applicazione. [Questa guida](https://docs.stripe.com/keys/restricted-api-keys.md) spiega come configurare e utilizzare le chiavi RAK. | | Chiave API pubblicabile | Sì | Chiave API che puoi inserire nel codice front-end o nelle applicazioni che distribuisci. | | Chiave API privata`sk_...` | No | Chiave API con autorizzazioni illimitate su tutte le API Stripe. Poiché non è possibile limitare tali autorizzazioni, sconsigliamo l’uso delle chiavi private per i nuovi casi d’uso; per le integrazioni esistenti, consigliamo invece di passare all’uso delle RAK. | | Chiave API dell’organizzazione`sk_org_...` | No | Chiave API che funziona a livello di organizzazione. Come le chiavi con limitazioni o private a livello di account, ma opera a livello di [organizzazione](https://docs.stripe.com/get-started/account/orgs.md) per gestire più account Stripe contemporaneamente. [Questa guida](https://docs.stripe.com/keys/organization-api-keys.md) spiega come configurare e utilizzare le chiavi API dell’organizzazione. | Accettiamo anche [chiavi API gestite](https://docs.stripe.com/keys/managed-api-keys.md) emesse da alcune piattaforme di hosting. Le chiavi gestite sono chiavi API segrete che una piattaforma di hosting consegna direttamente alle tue applicazioni in hosting. Non è necessario gestire direttamente le chiavi gestite: il tuo provider di hosting le emette e le sostituisce per te. > #### Segreti di firma webhook > > I segreti di firma dei webhook non sono chiavi API: si tratta di segreti specifici per ciascun webhook che il destinatario del webhook utilizza per verificare che i webhook provengano effettivamente da Stripe. Puoi trovare il segreto di firma per ciascun endpoint webhook nella sezione [Webhook](https://dashboard.stripe.com/webhooks) della Dashboard. Se hai creato il tuo account Stripe prima di maggio 2026, potresti non avere chiavi API con limitazioni. Ti consigliamo di creare RAK e migrare dalle chiavi private. Hai la responsabilità della gestione sicura delle tue chiavi API. Leggi la nostra guida alle [best practice per proteggere le chiavi API](https://docs.stripe.com/keys-best-practices.md). ### Sandbox e modalità live a confronto Tutte le richieste all’API Stripe avvengono in modalità *sandbox* (A sandbox is an isolated test environment that allows you to test Stripe functionality in your account without affecting your live integration. Use sandboxes to safely experiment with new features and changes) o *live* (Use this mode when you’re ready to launch your app. Card networks or payment providers process payments). Puoi utilizzare una sandbox per testare l’integrazione e accedere ai dati di test e la modalità live per accedere ai dati effettivi dell’account. Ciascuna modalità dispone di un proprio set di chiavi API e gli oggetti presenti in una modalità non sono accessibili dall’altra. Ad esempio, un [oggetto prodotto](https://docs.stripe.com/api/products/object.md) della sandbox non può far parte di un pagamento in modalità live. | Tipo | Quando si usano | Oggetti | Come si usano | Considerazioni | | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Sandbox | Utilizza una sandbox e le chiavi API di test associate mentre crei la tua integrazione. In una sandbox, i circuiti delle carte di credito e i fornitori di servizi di pagamento non elaborano i pagamenti. | Le chiamate API restituiscono oggetti simulati. Ad esempio, puoi recuperare e utilizzare gli oggetti test `account`, `payment`, `customer`, `charge`, `refund`, `transfer`, `balance` e `subscription`. | Utilizza [account e carte di credito di test](https://docs.stripe.com/testing.md#cards). Non puoi accettare metodi di pagamento reali né lavorare con account reali. | [Identy](https://docs.stripe.com/identity.md) non effettua alcuna verifica. Inoltre, gli [oggetti Account](https://docs.stripe.com/api/accounts/object.md) di Connect non restituiscono campi sensibili. | | Modalità live | Utilizza la modalità live, e le chiavi API live associate, quando sarà tutto pronto per lanciare l’integrazione e accettare denaro reale. In modalità live, i circuiti delle carte di credito e i fornitori di servizi di pagamento elaborano i pagamenti. | Le chiamate API restituiscono oggetti reali. Ad esempio, puoi recuperare e utilizzare gli oggetti reali `account`, `payment`, `customer`, `charge`, `refund`, `transfer`, `balance` e `subscription`. | Accetta carte di credito reali e lavora con gli account dei clienti. Puoi accettare autorizzazioni di pagamento, addebiti e acquisizioni reali per carte di credito e account. | Il flusso delle contestazioni è più dettagliato e la relativa [procedura di test](https://docs.stripe.com/testing.md#disputes) è più semplice. Inoltre, alcuni [metodi di pagamento](https://docs.stripe.com/payments/payment-methods.md) hanno un flusso più dettagliato e richiedono un maggior numero di passaggi. | ## Proteggi le tue chiavi Solo le chiavi pubblicabili possono essere divulgate in modo sicuro al di fuori del back-end della tua applicazione. Hai la responsabilità della protezione delle altre chiavi API Stripe, comprese quelle con limitazioni. Ecco alcuni modi per proteggere le tue chiavi: - Conserva le chiavi sensibili in un archivio di segreti fornito dalla tua piattaforma di hosting. [Questo articolo del blog](https://stripe.dev/blog/securing-stripe-api-keys-aws-automatic-rotation) offre un esempio. Se non puoi utilizzare un archivio di segreti, ricorri alle variabili d’ambiente per fornire le chiavi alle tue applicazioni back-end. - Non inserire le chiavi nel codice sorgente o nei file di configurazione gestiti tramite controllo di versione. - [Limita le chiavi a indirizzi IP specifici](https://docs.stripe.com/keys.md#limit-api-secret-keys-ip-address) in modo che solo i tuoi server possano utilizzarle. - [Sostituisci le chiavi](https://docs.stripe.com/keys.md#rolling-keys) quando i membri del team che hanno accesso alle chiavi lasciano la tua organizzazione. - Non condividere le chiavi via email, chat o altri canali non crittografati. Per una guida completa, consulta [le best practice per la gestione delle chiavi API private](https://docs.stripe.com/keys-best-practices.md). Inoltre, manteniamo [una libreria di skill](https://github.com/stripe/ai/tree/main/skills) per aiutare gli agenti di IA a seguire queste best practice. ## Gestisci le chiavi API Usa la [Dashboard](https://dashboard.stripe.com/apikeys) per creare, visualizzare, modificare, eliminare e sostituire le tue chiavi API. #### Creare una chiave API con limitazioni Utilizza le [chiavi API con limitazioni](https://docs.stripe.com/keys/restricted-api-keys.md) (RAK) per la maggior parte dei casi d’uso. Utilizzando una RAK, puoi assegnare esattamente le autorizzazioni necessarie alla tua integrazione, riducendo così i danni che un malintenzionato potrebbe causare alla tua attività qualora entrasse in possesso della tua chiave. - Segui le istruzioni in [Chiavi API con limitazioni](https://docs.stripe.com/keys/restricted-api-keys.md) per creare una RAK, configurarne le autorizzazioni ed eseguire la migrazione dalle chiavi private. #### Creare una chiave API privata Crea una chiave API privata senza limitazioni solo quando la tua integrazione richiede accesso a tutte le API e le risorse di Stripe senza limitazioni. Se un malintenzionato ottiene la tua chiave privata, può danneggiare la tua attività. Consigliamo di usare le RAK. 1. Nella scheda [Chiavi API](https://dashboard.stripe.com/test/apikeys), fai clic su **Crea chiave privata**. 1. Nella finestra di dialogo, inserisci il codice di verifica che ti inviamo via email o SMS. Se la finestra di dialogo non prosegue automaticamente, fai clic su **Continua**. 1. Inserisci un nome nel campo **Nome chiave**, quindi fai clic su **Crea**. 1. Fai clic sul valore chiave per copiarlo. 1. Salva il valore della chiave. Non potrai più recuperarlo. 1. Nel campo **Aggiungi una nota**, inserisci la posizione in cui hai salvato la chiave e fai clic su **Fine**. ### Rivelare una chiave API Quando crei una chiave privata in modalità live, te la mostriamo una sola volta prima che la salvi. Copia la chiave prima di salvarla, perché in seguito non potrai più visualizzarla. In modalità live, puoi visualizzare solo le chiavi API che creiamo per te, come una chiave privata predefinita o una chiave generata da una sostituzione pianificata. In modalità sandbox, puoi sempre vedere tutte le tue chiavi API, incluse quelle con limitazioni e quelle private. > Conserva le chiavi sensibili in un luogo dove non rischi di perderle, come ad esempio un vault di segreti fornito dalla tua piattaforma. Non inserire le chiavi nel codice della tua applicazione. Le chiavi API pubblicabili non contengono dati sensibili, pertanto vengono visualizzate per impostazione predefinita e non è necessario fare nulla per visualizzarle. Non possiamo recuperare le chiavi che hai dimenticato o alle quali non hai più accesso. Se perdi una chiave, sostituiscila o eliminala e creane un’altra. #### Per visualizzare una RAK in modalità live Puoi rivelare solo i RAK in modalità live che abbiamo creato per te. Se crei un RAK autonomamente, non potrai rivelarlo dopo averlo visto una volta. 1. Nella scheda [Chiavi API](https://dashboard.stripe.com/apikeys) in modalità live, nell’elenco **Chiavi con limitazioni**, fai clic su **Mostra chiave live** per la chiave che desideri visualizzare. 1. Fai clic sul valore chiave per copiarlo. 1. Salva il valore della chiave nel [vault delle chiavi private](https://docs.stripe.com/keys-best-practices.md#use-a-secrets-vault) della tua piattaforma. Se la tua piattaforma non ne fornisce uno, usa una variabile d’ambiente. 1. Fai clic su **Nascondi chiave live**. #### Per visualizzare una chiave API privata in modalità live Puoi visualizzare solo le chiavi private in modalità live che abbiamo creato per te. Se crei autonomamente una chiave privata, non potrai visualizzarla dopo averla vista una volta. 1. Nella scheda [Chiavi API](https://dashboard.stripe.com/apikeys) in modalità live, nell’elenco **Chiavi standard**, fai clic su **Rivela chiave live** per la chiave che desideri rivelare. 1. Fai clic sul valore chiave per copiarlo. 1. Salva il valore della chiave nel [vault delle chiavi private](https://docs.stripe.com/keys-best-practices.md#use-a-secrets-vault) della tua piattaforma. Se la tua piattaforma non ne fornisce uno, usa una variabile d’ambiente. 1. Fai clic su **Nascondi chiave live**. 1. Clicca sul menu di overflow (⋯), quindi seleziona **Modifica chiave** per la chiave a cui desideri aggiungere una nota. 1. Nel campo **Nota** inserisci la posizione in cui hai salvato la chiave, poi fai clic su **Salva**. ### Limitare una chiave API a determinati indirizzi IP Puoi circoscrivere una chiave API con limitazioni a un intervallo di indirizzi IP o a uno o più indirizzi IP specifici. Stripe consiglia di abilitare le limitazioni IP su tutte le chiavi in modalità live per impedire l’uso da località non autorizzate. Se applicabile, utilizza elenchi di consenso IP separati per chiavi separate (ad esempio, per distinguere tra ambienti di staging e di produzione). Gli indirizzi IP devono utilizzare il protocollo IPv4 e puoi specificare qualsiasi intervallo CIDR valido. Ad esempio,puoi specificare l’intervallo `100.10.38.0 - 100.10.38.255` come `100.10.38.0/24`. Tutti gli indirizzi IP nell’intervallo devono iniziare con `100.10.38`. 1. Nella scheda [Chiavi API](https://dashboard.stripe.com/test/apikeys), nell’elenco **Chiavi con limitazioni** o **Chiavi standard**, fai clic sul menu di overflow (⋯) e seleziona la chiave che vuoi rivelare. 1. Seleziona **Gestisci limitazioni IP** > **Limita l’uso a una serie di indirizzi IP**. 1. Esegui una delle seguenti operazioni: - Inserisci uno o più indirizzi IP nel campo **Indirizzo IP**. - Per un intervallo di indirizzi IP, inserire il primo indirizzo dell’intervallo (utilizzando la notazione CIDR, routing interdominio senza classi) nel campo **Indirizzo IP**. Inserisci la dimensione del prefisso di rete nel campo **CIDR**. 1. Per aggiungere un altro indirizzo IP o intervallo, fai clic su **+ Aggiungi**. 1. Fai clic su **Salva**. ### Modificare il nome o la nota di una chiave API 1. Nella scheda delle [chiavi API](https://dashboard.stripe.com/test/apikeys), fai clic sul menu di overflow (⋯) della chiave che vuoi modificare. 1. Seleziona **Modifica chiave**. 1. Procedi come segue: - Per modificare il nome, inserisci un nuovo nome nel campo **Nome chiave**. - Per modificare il testo della nota, inserisci il nuovo testo nel campo **Nota**. 1. Fai clic su **Salva**. ### Fai scadere una chiave API Se elimini una chiave API privata o una chiave API con limitazioni, devi crearne una nuova e aggiornare tutti i codici che utilizzano la chiave scaduta. Ogni codice che utilizza la chiave scaduta non potrà più effettuare chiamate API. > Non puoi far scadere una chiave pubblicabile. 1. Nella scheda [Chiavi API](https://dashboard.stripe.com/test/apikeys), nell’elenco **Chiavi con limitazioni** o **Chiavi standard**, fai clic sul menu di overflow (⋯) della chiave che desideri far scadere. 1. Seleziona **Scadenza chiave**. 1. Nella finestra di dialogo, fai clic su **Elimina chiave**. Se non vuoi più eliminarla, fai clic su **Annulla**. ### Ruotare una chiave API La rotazione di una chiave API la revoca e genera una chiave sostitutiva pronta da usare subito. Puoi anche possibile programmare la rotazione di una chiave API dopo un determinato periodo di tempo. La chiave sostitutiva viene denominata come segue: - Il nome della chiave pubblicabile sostitutiva è sempre `Publishable key`. - Il nome chiave privata sostitutiva è sempre `Secret key`. - La chiave con limitazioni sostitutiva ha lo stesso nome della chiave ruotata. Puoi rinominare una chiave API privata, o con limitazioni, modificandola. Ruota la chiave API in scenari come: - Se perdi una chiave API privata, o con limitazioni, in modalità live e non puoi recuperarla dalla Dashboard. - Se una chiave API privata o con limitazioni viene compromessa, è necessario revocarla per bloccare eventuali richieste API potenzialmente dannose che potrebbero utilizzare la chiave. - Se un membro del team con accesso alla chiave lascia la tua organizzazione o cambia ruolo. - Se la tua policy richiede la rotazione delle chiavi a determinati intervalli. #### Per ruotare una chiave API: 1. Nella scheda delle [chiavi API](https://dashboard.stripe.com/test/apikeys), fai clic sul menu extra (⋯) della chiave che vuoi ruotare. 1. Seleziona **Ruota chiave**. 1. Seleziona una data di scadenza dal menu a discesa **Scadenza**. Se selezioni **Ora**, la chiave precedente viene eliminata. Se specifichi un’ora, sotto il nome della chiave viene mostrato il tempo rimanente fino alla scadenza della chiave. 1. Fai clic su **Ruota chiave API**. 1. Fai clic sul valore chiave per copiarlo. 1. Salva il valore della chiave. Non potrai più recuperarlo. 1. Nel campo **Aggiungi una nota** inserisci la posizione in cui hai salvato la chiave, quindi fai clic su **Salva** o **Fine**. ### Ripristina l’accesso a una chiave API Una chiave API può avere un accesso limitato se non è stato utilizzata per creare trasferimenti, bonifici o aggiornare destinazioni di bonifico per oltre 180 giorni. Non è possibile utilizzare una chiave con accesso limitato per creare bonifici e trasferimenti o per creare destinazioni di bonifico. È possibile ripristinare l’accesso per utilizzare il codice normalmente o per eseguire un’azione bloccata. #### Per ripristinare l’accesso per una chiave API 1. Nella scheda delle [chiavi API](https://dashboard.stripe.com/test/apikeys), fai clic sul menu extra (⋯) della chiave che vuoi ripristinare. 1. Seleziona **Ripristina accesso**. 1. Fai clic su **Ripristina**. ## Visualizza i log delle richieste API per una chiave Per [aprire i log di richieste API](https://docs.stripe.com/development/dashboard/request-logs.md), fai clic sul menu di overflow (⋯) di qualsiasi chiave, quindi seleziona **Visualizza log richieste**. L’apertura dei registri reindirizza alla Dashboard Stripe. ## Passa alla modalità live Quando è tutto pronto per accettare pagamenti reali, utilizza le chiavi API in modalità live anziché quelle in modalità sandbox (di prova). Nella pagina delle [chiavi API](https://dashboard.stripe.com/apikeys), passa dalla **modalità sandbox** alla **modalità live**. La pagina ora mostra le tue chiavi API in modalità live. > #### Lista di controllo completa per l'attivazione del servizio > > Cambiare chiave API è solo un passaggio. Rivedi la [checklist di attivazione del servizio](https://docs.stripe.com/get-started/checklist/go-live.md) completa per assicurarti che la tua integrazione sia pronta per la produzione. ### Chiavi pubblicabili (lato client) Copia la tua **chiave pubblicabile in modalità live** (che inizia con `pk_live_`) e sostituisci la chiave `pk_test_` nel codice lato client. È sicuro incorporare questa chiave nel codice o nelle app. ### Chiavi API con limitazioni o private (lato server) Le chiavi API lato server sono dati sensibili; pertanto, ti invitiamo a consultare le nostre [best practice per la gestione delle chiavi API private](https://docs.stripe.com/keys-best-practices.md). Ti consigliamo di generare [chiavi API con limitazioni](https://docs.stripe.com/keys/restricted-api-keys.md) per il tuo codice lato server, in modo da limitare i danni alla tua attività nel caso in cui le chiavi venissero divulgate o compromesse. 1. Prima di iniziare a usare una chiave in modalità live nella tua applicazione back-end, rimuovi dal codice eventuali chiavi API hardcoded. Usa invece un [vault delle chiavi private](https://docs.stripe.com/keys-best-practices.md#use-a-secrets-vault) per fornire la chiave sandbox e verifica che la tua richiesta di registrazione funzioni correttamente. Se la tua piattaforma non fornisce un vault delle chiavi private, puoi usare una variabile di ambiente. 1. [Visualizza](https://docs.stripe.com/keys.md#reveal-an-api-key) e copia le tue **chiavi in modalità live** (che iniziano con `rk_live_` o `sk_live_`) e archiviale in modo sicuro nel tuo ambiente server. 1. Configura il tuo ambiente server per fornire chiavi in modalità live anziché chiavi sandbox alla tua richiesta di registrazione. #### Chiavi di firma dei webhook (lato server) Se utilizzi i webhook, aggiorna l’URL di ciascun endpoint webhook e copia la nuova **chiave privata di firma** dalla sezione [Webhook](https://dashboard.stripe.com/webhooks) della Dashboard. ## See also - [Best practice per la gestione di chiavi API private](https://docs.stripe.com/keys-best-practices.md) - [Protezione dalle chiavi API compromesse](https://support.stripe.com/questions/protecting-against-compromised-api-keys) - [Perché la mia chiave API ha accesso limitato](https://support.stripe.com/questions/why-does-my-api-key-have-limited-access)