Chiavi 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. Se una richiesta include una chiave eliminata o scaduta, Stripe restituisce un errore di autenticazione.

Utilizza la Dashboard per sviluppatori per creare, rivelare, eliminare e ruotare chiavi API. Per accedere alle chiavi API v1, seleziona la scheda Chiavi API sulla tua Dashboard.

Tipi di chiave

Per impostazione predefinita, tutti gli account dispongono di un totale di quattro chiavi API, due in una sandbox e due in metodo live:

• Chiave privata della sandbox: Questa chiave ti permette di autenticare le richieste al tuo server quando effettui test in modalità sandbox. Per impostazione predefinita, puoi utilizzare questa chiave per eseguire qualsiasi richiesta API senza limitazioni. Riserva questa chiave per i test e lo sviluppo, per assicurarti di non modificare accidentalmente i clienti o gli addebiti live.
• Chiave pubblicabile sandbox: Utilizza questa chiave per eseguire dei test a livello di codice lato client della tua app web o per dispositivi mobili. Riserva questa chiave per i test e lo sviluppo, per assicurarti di non modificare accidentalmente i clienti o gli addebiti live.
• Chiave privata per la modalità live: utilizza questa chiave per autenticare le richieste sul server in modalità live. Per impostazione predefinita, puoi utilizzare questa chiave per eseguire qualsiasi richiesta API senza limitazioni.
• Chiave pubblicabile per la modalità live: utilizza questa chiave, quando sarai pronto a lanciare l’app, nel codice lato client della tua app web o per dispositivi mobili.

Le chiavi private e pubblicabili si trovano nella Dashboard nella scheda chiavi API. Se non riesci a visualizzare le chiavi API, chiedi al titolare dell’account Stripe di aggiungerti al suo team con le autorizzazioni appropriate.

Quando accedi a Stripe, la nostra documentazione popola automaticamente gli esempi di codice con le tue chiavi API di test. Solo tu puoi vedere questi valori. Se non hai effettuato l’accesso, alcuni esempi di codice includono chiavi API generate in modo casuale. Puoi sostituirle con le tue chiavi di test o accedere per vedere esempi di codice popolati con le tue chiavi API di test.

La tabella seguente mostra esempi generati casualmente di chiavi API private di prova e pubblicabili:

Sandbox e modalità live a confronto

Tutte le richieste API Stripe vengono effettuate in modalità sandbox o live. Utilizza una sandbox per accedere ai dati di test e la modalità live per accedere ai dati effettivi dell’account. Ogni modalità ha il proprio set di chiavi API. Gli oggetti in una modalità non sono accessibili nell’altra. Ad esempio, un oggetto Productnon può far parte di un pagamento in modalità live.

Ruotare una chiave API

La rotazione di una chiave viene revocata e viene generata una chiave sostitutiva. Puoi ruotare una chiave immediatamente o programmarne la rotazione dopo un determinato periodo di tempo. Ruota una chiave in scenari come negli esempi seguenti:

• Se sei in modalità live e perdi una chiave privata o una chiave con limitazioni, non puoi recuperarla dalla Dashboard e devi sostituirla.
• Se una chiave privata o con limitazioni è compromessa, devi revocarla per bloccare eventuali richieste API potenzialmente dannose che potrebbero utilizzarla.
• La tua politica richiede la rotazione delle chiavi a determinati intervalli.

Per ruotare una chiave API:

1. Apri la pagina delle chiavi API.
2. Nella riga relativa alla chiave che vuoi ruotare, fai clic sul menu extra (), poi seleziona Ruota chiave.
3. Scegli una data di scadenza dal menu discesa Scadenza.
4. Fai clic su Ruota chiave API.
5. La finestra di dialogo visualizza il nuovo valore della chiave. Copialo facendo clic su di esso.
6. Salva il valore della chiave. Non potrai più recuperarlo.
7. Nel campo Aggiungi una nota, inserisci la posizione in cui hai salvato la chiave e fai clic su Fine o Salva.

Se hai scelto Ora per Scadenza, la chiave precedente viene eliminata. Se hai selezionato un’ora diversa, sotto il nome puoi visualizzare il tempo rimanente alla scadenza della chiave.

Indipendentemente dal tempo di scadenza della chiave precedente, la nuova chiave è pronta per l’uso immediatamente.

Quando ruoti una chiave pubblicabile, il nome della chiave sostitutiva è sempre Publishable key. Quando ruoti una chiave privata, il nome della chiave sostitutiva è sempre Secret key. Quando ruoti una chiave con limitazioni, il nome della chiave sostitutiva è lo stesso della chiave ruotata. Puoi rinominare una chiave privata o con limitazioni facendo clic sul relativo menu extra e selezionando Modifica chiave.

Visualizzare i log delle richieste API

Per aprire i log di richieste API, fai clic sul menu extra () per qualsiasi chiave, poi seleziona Visualizza log richieste. Quando apri i log, vieni reindirizzato alla Dashboard Stripe principale.

Chiavi private e con limitazioni

Utilizza la Dashboard per creare, eliminare, rivelare e modificare chiavi private e con limitazioni.

Creare una chiave API privata

Per creare una chiave API privata:

1. Apri la pagina delle chiavi API.
2. Fai clic su Crea chiave privata.
3. Stripe invia un codice di verifica al tuo indirizzo email o in un SMS. Come per qualsiasi email o SMS, potrebbe non arrivare immediatamente. Inserisci il codice nella finestra di dialogo. Se la finestra di dialogo non continua automaticamente, fai clic su Continua.
4. Inserisci un nome nel campo Nome chiave.
5. Fai clic su Crea.
6. La finestra di dialogo visualizza il nuovo valore della chiave. Copialo facendo clic su di esso.
7. Salva il valore della chiave. Non potrai più recuperarlo.
8. Nel campo Aggiungi una nota, inserisci la posizione in cui hai salvato la chiave e fai clic su Fatto.

Creare una chiave API con limitazioni

Una chiave API con limitazioni consente solo il livello di accesso specificato.

Per creare una chiave API con limitazioni:

1. Apri la pagina delle chiavi API.
2. Puoi creare una chiave con limitazioni da zero o iniziare clonando una chiave con limitazioni esistente.
   • Per creare da zero una chiave con limitazioni, fare clic su Crea chiave con limitazioni. In questo caso, il valore predefinito per tutte le autorizzazioni è Nessuna.
   • Per clonare una chiave esistente, nella riga della chiave che vuoi clonare fai clic sul menu extra () e seleziona Duplica chiave. In questo caso, il valore predefinito per ogni autorizzazione è il relativo valore nella chiave clonata.
3. Nel campo ** Nome chiave **, inserisci un nome. Se è stata clonata una chiave esistente, il nome predefinito corrisponde al nome della chiave clonata.
4. Per ogni risorsa a cui vuoi concedere l’accesso alla nuova chiave, seleziona l’autorizzazione che vuoi concedere per la chiave. Se utilizzi Connect, puoi anche selezionare l’autorizzazione per consentire l’uso di questa chiave quando accedi agli account connessi. Le autorizzazioni disponibili sono Nessuna, Lettura o Scrittura.
5. Fai clic su Crea chiave.
6. Stripe invia un codice di verifica al tuo indirizzo email o in un SMS. Come per qualsiasi email o SMS, potrebbe non arrivare immediatamente. Inserisci il codice nella finestra di dialogo. Se la finestra di dialogo non continua automaticamente, fai clic su Continua.
7. La finestra di dialogo visualizza il nuovo valore della chiave. Copialo facendo clic su di esso.
8. Salva il valore della chiave. Non potrai più recuperarlo.
9. Nel campo Aggiungi una nota, inserisci la posizione in cui hai salvato la chiave e fai clic su Fatto.

Eliminare una chiave API privata o con limitazioni

Se elimini una chiave, qualsiasi codice che utilizza tale chiave non può più effettuare chiamate API. Dopo aver eliminato una chiave, creane una nuova e aggiorna il codice per usarla.

Per eliminare una chiave:

1. Nella Dashboard per sviluppatori, seleziona la scheda delle chiavi API.
2. Individua la chiave che vuoi eliminare nell’elenco Chiavi standard o Chiavi con limitazioni. Nella riga di quella chiave, fai clic sul menu extra () e seleziona Elimina chiave.
3. Se vuoi davvero procedere all’eliminazione della chiave, fai clic su Elimina chiave nella finestra di dialogo Elimina chiave API. Altrimenti, fai clic su Annulla.

Rivelare una chiave API privata in una sandbox

con le sandbox, puoi rivelare una chiave API privata tutte le volte che vuoi.

Rivelare una chiave privata in una sandbox:

1. Nella Dashboard per sviluppatori, seleziona la scheda delle chiavi API.
2. Nell’elenco Chiavi standard, fai clic su Rivela chiave di test nella riga Chiave privata.
3. Copia il valore della chiave facendo clic su di esso.
4. Salva il valore della chiave.
5. Fai clic su Nascondi chiave di test.

Rivelare una chiave API privata o con limitazioni per la modalità live

Per motivi di sicurezza, in modalità live Stripe mostra solo una volta una chiave API privata o con limitazioni. Conserva la chiave in un luogo per non perderla. Per ricordarti dove l’hai memorizzata, puoi lasciare una nota sulla chiave nella Dashboard. Se perdi la chiave, puoi ruotarla o eliminarla e crearne un’altra.

Per rivelare una chiave privata o con limitazioni in modalità live e allegare una nota:

1. Nella Dashboard per sviluppatori, seleziona la scheda delle chiavi API.
2. Fai clic su Rivela chiave live nell’elenco Chiavi standard o Chiavi con limitazioni nella riga relativa alla chiave che vuoi rivelare.
3. Copia il valore della chiave facendo clic su di esso.
4. Salva il valore della chiave.
5. Fai clic su Nascondi chiave di test.
6. Fai clic sul menu extra () accanto alla chiave e seleziona Modifica chiave.
7. Nel campo Nota, inserisci la posizione in cui hai salvato la chiave e fai clic su Salva.
8. Se hai creato la chiave prima che Stripe introducesse questa funzionalità, fai clic su Nascondi chiave attiva.

Limitare le chiavi private o con limitazioni a un elenco o a un intervallo di indirizzi IP

Per limitare le richieste API che utilizzano una chiave a uno o più indirizzi IP specifici o a un intervallo di indirizzi IP:

1. Apri la pagina delle chiavi API.
2. Fai clic sul menu extra () nell’elenco Chiavi standard o Chiavi con limitazioni nella riga relativa alla chiave che vuoi rivelare e seleziona Gestisci limitazioni IP.
3. Fai clic su Limita l’uso a una serie di indirizzi IP.
4. Inserisci un indirizzo IP o un intervallo di indirizzi IP:
   • Inserisci ogni singolo indirizzo nel campo Indirizzo IP.
   • Per un intervallo di indirizzi IP, inserisci l’intervallo nella notazione CIDR (Classless Inter-Domain Routing). Nel campo Indirizzo IP inserisci il primo indirizzo nell’intervallo. Nel campo CDR inserisci la dimensione del prefisso di rete.
   • Puoi anche selezionare la scheda Gestisci in blocco e inserire indirizzi IP singoli e intervalli, separati da spazi. Le modifiche apportate in una scheda vengono visualizzate nell’altra scheda.
5. Per aggiungere un altro indirizzo o intervallo, fai clic su + Aggiungi.
6. Fai clic su Salva.

Modificare il nome o la nota di una chiave API privata o con limitazioni

Per modificare il nome o il testo della nota di una chiave privata o con limitazioni:

1. Apri la pagina delle chiavi API.
2. Fai clic sul menu extra () nella riga relativa alla chiave che vuoi modificare e seleziona Modifica chiave.
3. Se vuoi modificare il nome, inserisci il nuovo nome in ** Nome chiave**.
4. Se vuoi modificare il testo della nota, inserisci il nuovo testo in Nota.
5. Fai clic su Salva.

Proteggere le proprie chiavi

Chiunque può utilizzare la chiave API privata in modalità live per effettuare qualsiasi chiamata API per conto del proprio account, come la creazione di un addebito o l’esecuzione di un rimborso. Tieni le chiavi al sicuro seguendo queste pratiche ottimali per le chiavi API private.