# Chiavi API con limitazioni

Le chiavi API con limitazioni si utilizzano per controllare l'accesso della tua applicazione all'API di Stripe.

Puoi utilizzare una chiave API con limitazioni per assegnare autorizzazioni specifiche dell’API di Stripe alle tue chiavi API. L’utilizzo di una chiave API con limitazioni limita i danni potenziali alla tua attività se una chiave API diventa accessibile a un malintenzionato. Se una chiave API con limitazioni non dispone delle autorizzazioni corrette per completare una richiesta API, Stripe restituisce un [errore di richiesta non valida](https://docs.stripe.com/error-handling.md#invalid-request-errors).

## Che cos’è una chiave API con limitazioni

Quando crei il tuo account Stripe, ottieni una [chiave API privata](https://docs.stripe.com/keys.md#obtain-api-keys) (inizia con `sk_live_` o `sk_test_`). Con la tua chiave privata, qualsiasi persona, agente o sistema può fare *qualsiasi cosa* nel tuo account Stripe: creare addebiti, emettere rimborsi, leggere i dati dei clienti, attivare bonifici e molto altro.

Una chiave API con limitazioni (RAK) inizia con `rk_live_` o `rk_test_` e può fare solo ciò che vuoi tu. Quando crei una RAK nella Dashboard di Stripe, selezioni le risorse di Stripe a cui può accedere la chiave, insieme alle autorizzazioni per ciascuna risorsa: **Lettura**, **Scrittura** o **Nessuna**. Tutte le API di Stripe supportano le chiavi API con limitazioni.

Puoi utilizzare chiavi con limitazioni come misura difensiva per proteggere il tuo account Stripe nel caso in cui le tue chiavi siano esposte o compromesse. Se un malintenzionato ottiene una chiave API con limitazioni, è limitato alle autorizzazioni di quella chiave. Ad esempio, puoi creare una chiave con limitazioni in grado di leggere solo i dati delle contestazioni e nient’altro. Se un malintenzionato ottiene quella chiave, può leggere solo i dati delle contestazioni. Non può creare addebiti, accedere ai metodi di pagamento dei clienti o avviare bonifici.

Stripe consiglia di utilizzare sempre le chiavi con limitazioni invece delle chiavi private illimitate. Segui sempre le best practice quando utilizzi le chiavi con limitazioni per evitare esposizioni o accidentali compromissioni. Leggi le [best practice per la gestione delle chiavi API private](https://docs.stripe.com/keys-best-practices.md).

## Perché le utilizzare chiavi con limitazioni invece delle chiavi private

|                                     | Chiave privata (`sk_`)                                     | Chiave con limitazioni (`rk_`)                                      |
| ----------------------------------- | ---------------------------------------------------------- | ------------------------------------------------------------------- |
| **Ambito di accesso**               | Accesso completo a ogni risorsa dell’API                   | Solo le autorizzazioni assegnate                                    |
| **Impatto se compromessa**          | Un malintenzionato può fare qualsiasi cosa nel tuo account | Un malintenzionato può fare solo ciò che consente la chiave         |
| **Condivisione di terze parti**     | Pericolosa: concede alla terza parte il pieno controllo    | Più sicura: concede l’accesso solo a ciò che serve alla terza parte |
| **Principio del privilegio minimo** | Non ottenibile con le chiavi senza limitazioni             | Puoi concedere autorizzazioni minime alle chiavi                    |
| **Raccomandazione Stripe**          | Usare con parsimonia e proteggere in modo aggressivo       | **Preferito**: usa chiavi con limitazioni, ove possibile            |

### Motivi per passare alle chiavi API con limitazioni

- **Limitare l’impatto di un’eventuale acquisizione della chiave**: se una chiave con limitazioni viene compromessa, un malintenzionato può accedere solo alle particolari risorse a cui hai consentito l’accesso.

- **Condividere le chiavi con terze parti in modo sicuro**: nella maggior parte dei casi, Stripe sconsiglia la condivisione delle chiavi, ma per alcune integrazioni di terze parti potrebbe essere necessario condividere una chiave. Ad esempio, se un fornitore deve monitorare le contestazioni, gli puoi fornire una chiave con limitazioni in grado di accedere alle contestazioni in sola lettura, non la tua chiave privata illimitata. Se lavori con terze parti, assicurati che seguano le [best practice](https://docs.stripe.com/keys-best-practices.md) per gestire la chiave in modo sicuro, come utilizzare un elenco di IP consentiti, se possibile, per ridurre il rischio che la chiave venga compromessa, e far scadere la chiave se termina il rapporto.

- **Soddisfare le aspettative riguardo alla conformità**: molti controlli di sicurezza e schemi di conformità si aspettano che tu segua il principio del privilegio minimo. Le chiavi con limitazioni semplificano questo processo.

- **Combinare con le limitazioni dell’IP**: per un ulteriore livello di difesa, puoi legare qualsiasi chiave con limitazioni a un insieme specifico di indirizzi IP.

## Migrazione da una chiave privata a una chiave con limitazioni

Le chiavi API con limitazioni sostituiscono le chiavi API private. Per utilizzare una chiave API con limitazioni, passala al tuo codice nello stesso modo in cui passi una chiave privata, seguendo le [best practice](https://docs.stripe.com/keys-best-practices.md) per evitare di esporre accidentalmente la chiave. Ogni API di Stripe supporta le chiavi API con limitazioni. Per ottenerne i vantaggi, devi configurare le autorizzazioni di ogni singola chiave con limitazioni.

Ecco un approccio dettagliato per eseguire la migrazione da una chiave privata a una chiave con limitazioni. Consulta [Assegnazione delle autorizzazioni a una chiave API con limitazioni](https://docs.stripe.com/keys/restricted-api-keys.md#assign-permissions) per capire come ridurre le autorizzazioni di una chiave con limitazioni.

### Esame dell’utilizzo della chiave API privata

Esamina il codice e le integrazioni di terze parti per catalogare i prodotti Stripe che utilizzi e le chiamate API effettuate attualmente con la tua chiave privata.

Esamina i [log delle richieste di chiave privata in Workbench](https://dashboard.stripe.com/workbench/logs). Puoi utilizzare la tabella che segue per mappare le richieste API riuscite con le autorizzazioni RAK necessarie.

| Metodo HTTP | Tipo di autorizzazione RAK |
| ----------- | -------------------------- |
| GET         | lettura                    |
| POST        | scrittura                  |
| DELETE      | scrittura                  |

Ad esempio, se vedi chiamate riuscite a `GET /v1/customers`, devi aggiungere le autorizzazioni in lettura per la risorsa [Customer](https://docs.stripe.com/api/customers.md) a una autorizzazione RAK sostitutiva.

### Creazione di una chiave con limitazioni in una sandbox

Prima di creare una chiave in modalità live, Stripe consiglia di creare una chiave con limitazioni in una sandbox Stripe.

1. Vai alla [pagina delle chiavi API](https://dashboard.stripe.com/apikeys) nella Dashboard di Stripe.
1. Fai clic su **Crea chiave con limitazioni**.
1. Fornisci un nome descrittivo, come `Test servizio fatturazione`.
1. Per ogni risorsa, imposta l’autorizzazione su **Nessuna**, **Lettura** o **Scrittura** on base all’utilizzo dell’API osservato in precedenza.

### Configura il tuo ambiente di prova per l’utilizzo della chiave con limitazioni

Nella tua richiesta di test o di prova dell’applicazione, nel tuo ambiente server sostituisci la chiave privata con la chiave con limitazioni (ad esempio, in una variabile d’ambiente o in un vault di chiavi private). L’SDK di Stripe e le chiamate HTTP che utilizzano la tua chiave funzionano in modo identico. L’unica differenza è il valore della chiave.

### Rivedi i log delle richieste della chiave con limitazioni per individuare eventuali errori, quindi adegua le autorizzazioni

Rivedi i log della chiave con limitazioni in modalità di test nell’[elenco delle chiavi](https://dashboard.stripe.com/apikeys) facendo clic sul menu di overflow (⋯) accanto alla chiave e selezionando **Visualizza registri richieste**.

Se trovi messaggi di errore come `403 ERR`, modifica le autorizzazioni della chiave con limitazioni aggiungendo le azioni non riuscite:

1. Fai clic sul menu di overflow (⋯) accanto alla chiave.
1. Seleziona **Modifica chiave**.
1. Ripeti i test in una sandbox per confermare di avere assegnato le autorizzazioni corrette alla chiave con limitazioni.

Verifica la presenza di errori delle API di Stripe nei registri delle richieste dell’applicazione. Se la chiave con limitazioni inviata insieme a una richiesta non dispone delle autorizzazioni corrette, il corpo della risposta include un messaggio di errore che spiega quali autorizzazioni aggiungere.

### Creazione di una chiave con limitazioni in modalità live

Crea una nuova chiave con limitazioni in modalità live, con le stesse autorizzazioni della chiave che hai testato in modalità di test.

### Configura il tuo ambiente di produzione in modo da utilizzare la chiave con limitazioni

Usa la nuova chiave nell’ambiente di produzione, nello stesso modo in cui hai configurato la chiave di test nel tuo ambiente di prova.

### Ritira la vecchia chiave privata

Quando hai la certezza che tutto funziona in modalità di test, nella Dashboard [ruota](https://docs.stripe.com/keys.md#rolling-keys) o [fai scadere](https://docs.stripe.com/keys.md#delete-secret-key) la vecchia chiave privata. In questo modo, nessuno la potrà utilizzare in futuro. Se desideri una finestra di sicurezza in cui puoi comunque ripristinare la chiave privata, puoi posticipare la scadenza (fino a 7 giorni).

## Assegnare le autorizzazioni a una chiave API con limitazioni

Puoi configurare chiavi con limitazioni per adeguarle ai tuoi casi d’uso particolari, basandoti sul principio del privilegio minimo: una chiave deve avere le autorizzazioni minime necessarie per svolgere il suo lavoro e nessuna di più. Ecco alcuni approcci pratici per assegnare le autorizzazioni.

### Controlla il registro delle richieste per determinare le autorizzazioni

1. Vai alla pagina delle [chiavi API](https://dashboard.stripe.com/apikeys) nella Dashboard.
1. Trova la chiave con limitazioni che stai configurando.
1. Fai clic sul menu di overflow (⋯) accanto alla chiave.
1. Fai clic su **Visualizza registro delle richieste** per visualizzare tutte le richieste effettuate con quella chiave.

Esamina gli endpoint API utilizzati dalla tua applicazione durante il test della chiave con limitazioni, per vedere esattamente quali risorse ha utilizzato la tua applicazione, e se vi hai letto o scritto:

- Le richieste `GET` sono di lettura
- Le richieste `POST` ed `ELIMINA` sono di scritture

Se la tua applicazione ha funzionato correttamente durante il test, compila un elenco delle chiamate andate a buon fine nei registri delle richieste, quindi confronta l’elenco con le autorizzazioni concesse alla chiave con limitazioni. Puoi quindi rimuovere dalla chiave tutte le autorizzazioni non utilizzate. Per modificare le autorizzazioni della chiave:

1. Fai clic sul menu di overflow(⋯).
1. Fai clic su **Modifica chiave**.

Se la tua applicazione non funziona correttamente, puoi filtrare i registri delle richieste della chiave per visualizzare le richieste non andate a buon fine, quindi modificare le autorizzazioni della chiave nel menu delle chiavi, aggiungendo le corrispondenti autorizzazioni dell’API di Stripe.

### Rivedi il codice

Puoi creare un elenco delle autorizzazioni richieste cercando le chiamate all’SDK di Stripe nella tua base di codice. Mappa ogni chiamata sulla corrispondente autorizzazione nella Dashboard. Ad esempio:

- `PaymentIntent.create(...)` → **PaymentIntents: Write**
- `Customer.retrieve(...)` → **Customers: Read**
- `Dispute.list(...)` → **Disputes: Read**

Quindi configura le autorizzazioni della tua chiave con limitazioni in modo che corrispondano soltanto a ciò che hai trovato.

### Inizia con le autorizzazioni generali, quindi rimuovi ciò che non ti serve

Inizialmente, a una chiave con limitazioni puoi concedere le autorizzazioni generali, quindi rimuovere le eventuali autorizzazioni in eccesso dopo aver esaminato come viene utilizzata la chiave.

In una sandbox, crea una chiave con limitazioni dal menu delle chiavi API. Le autorizzazioni disponibili sono raggruppate per categorie. Se sai che il tuo utilizzo dell’API di Stripe non include una categoria particolare, ad esempio Stripe Billing, puoi selezionare **None** per quella categoria. Altrimenti, seleziona **Write** per le categorie rilevanti per l’utilizzo dell’API di Stripe. Le autorizzazioni **Write** includono le autorizzazioni **Read**: se una chiave è in grado di scrivere una risorsa API, può anche leggere quella risorsa.

Testa la tua applicazione con la chiave con limitazioni in modalità di test, come descritto in precedenza, in modo che la tua applicazione utilizzi la chiave per inviare le richieste all’API di Stripe. Testa ogni componente della tua applicazione che utilizza le API di Stripe.

## Usa un’unica chiave con con limitazioni per ciascun servizio o caso d’uso

Se disponi di più servizi che utilizzano le API di Stripe (ad esempio, un servizio di fatturazione, un servizio di reportistica e un gestore di webhook), crea una chiave con limitazioni separata per ciascun servizio e concedi a ciascuna chiave solo le autorizzazioni dell’API di Stripe che servono a ciascun servizio. La concessione di autorizzazioni separate consente di limitare il potenziale impatto del furto di una chiave, qualora venga compromesso uno qualsiasi dei servizi.