Come creare o clonare una chiave API privata

Cosa imparerai

Scopri come creare o clonare una chiave API privata e scegliere gli ambiti che controllano a cosa può accedere un'applicazione nel tuo account Klaviyo.

Sia le chiavi API private sia gli ambiti ti aiutano a proteggere i tuoi dati e quelli della tua clientela limitando ciò a cui le terze parti possono accedere.

Informazioni su chiavi API private e ambiti

Una chiamata API consente a un'applicazione di richiedere, aggiungere o modificare informazioni in un'altra applicazione.

Una chiave API privata identifica il tuo account Klaviyo e autorizza le richieste API utilizzando gli ambiti assegnati alla chiave. Chiunque abbia la chiave può utilizzare queste autorizzazioni, quindi trattala come una password.

Includere un ambito per una chiave API privata aggiunge un ulteriore livello di autorizzazione, limitando gli elementi specifici a cui può accedere una terza parte. Gli ambiti sono simili a una chiave di un hotel, che ti dà accesso solo a determinate aree (come la tua stanza o la palestra) e non all’intero edificio.

Definisci l’ambito dei livelli di accesso

Quando crei una chiave API privata, scegli un livello di accesso per ogni ambito API. Questi livelli di accesso determinano se una terza parte può:

• Non avere accesso ai dati o alle azioni coperti da tale ambito.
• Visualizza i dati coperti da tale ambito senza apportare modifiche (accesso in lettura).
• Visualizza i dati e crea, elimina o apporta altre modifiche incluse in tale ambito (accesso in lettura/scrittura).

Ad esempio, per iscrivere i profili al marketing e aggiungerli a una lista Klaviyo da un’altra applicazione, usa Iscrivi profili in blocco. Questo endpoint richiede lists:write, profiles:write e subscriptions:write. Concedere l’accesso in lettura/scrittura per questi ambiti copre questa richiesta; non devi concedere l’accesso ad ambiti non correlati.

Puoi scoprire le API di Klaviyo e vedere gli ambiti disponibili per ogni endpoint sul portale di sviluppo.

Prima di iniziare

Nota quanto segue:

• Dopo aver creato una chiave API privata, non puoi:
  • Visualizza di nuovo la chiave API privata completa dopo aver lasciato la pagina di conferma.
    • Suggerimento: salva in modo sicuro le chiavi API private e annota per cosa vuoi usarle, ad esempio in un gestore di password.
  • Aggiungi o modifica i suoi ambiti.
    • Se ti servono ambiti diversi, crea una nuova chiave API privata con l'accesso richiesto. Aggiorna tutte le integrazioni che usano la vecchia chiave e verifica che funzionino prima di eliminarla.
• La pagina di creazione si apre con Chiave personalizzata selezionata. Scegli l’accesso per almeno 1 ambito API prima di creare la chiave.

Se non sai quali endpoint API, ambiti o autorizzazioni ti servono, contatta uno sviluppatore o rivolgiti a un partner Klaviyo per ricevere supporto.

Crea una chiave API privata

1. Clicca sul nome della tua organizzazione in basso a sinistra.
2. Vai su Impostazioni.
3. Click chiave API.
   

4. Clicca su Crea una chiave API privata.
5. Assegna un nome alla chiave API.
6. In Seleziona livello di accesso, scegli l’accesso di cui ha bisogno la tua integrazione:
   • Chiave di sola lettura: concede l'accesso in lettura per tutti gli ambiti API disponibili.
   • Chiave di accesso completo: concede l’accesso in lettura/scrittura per tutti gli ambiti API disponibili.
   • Chiave personalizzata: ti consente di scegliere Nessun accesso, Accesso in lettura o Accesso in lettura/scrittura per ogni riga in Ambiti API. Seleziona l'accesso per almeno 1 ambito.

7. Seleziona Crea.
8. Nella pagina di conferma, usa l’icona di copia (Copia chiave) o l’icona di download (Scarica (.txt)) per salvare la chiave in un luogo sicuro. Non puoi più visualizzare di nuovo la chiave completa dopo aver lasciato questa pagina.
9. Seleziona Chiudi per tornare a chiavi API.

Ora, quando condividi una chiave API privata, la terza parte avrà accesso solo alle informazioni che hai definito nell’ambito.

Clona una chiave API privata

La clonazione crea una nuova chiave API privata utilizzando gli scope della chiave originale. Gli scope rinominati utilizzano i loro nomi attuali e gli scope deprecati senza una sostituzione vengono omessi.

Nota:

• La clonazione non genera la stessa chiave della chiave API privata originale.
• Una chiave API clonata ha lo stesso nome dell'originale. Non puoi rinominarla nelle impostazioni delle chiavi API.

Per clonare una chiave API privata:

1. Vai su Impostazioni > Chiavi API.
2. Clicca sul menu con i 3 puntini accanto alla chiave che vuoi clonare.
3. Seleziona Clona, quindi seleziona di nuovo Clona nella finestra di dialogo di conferma.

4. Usa l'icona di copia (Copia chiave) o l'icona di download (Scarica (.txt)) per salvare la nuova chiave in un luogo sicuro, poi seleziona Chiudi. Non puoi più visualizzare la chiave completa dopo aver chiuso questa pagina.
5. Se stai sostituendo la chiave originale, aggiorna tutte le integrazioni che la utilizzano e conferma che funzionino con la nuova chiave. Elimina l’originale solo quando non è più necessaria.

Utilizzo dei parametri di query

Il parametro include aggiunge dati correlati a una risposta API. Il parametro scopes preseleziona le autorizzazioni nella pagina di creazione della chiave API privata. Questi sono utilizzi avanzati separati dei parametri di query dell'URL. Se non ti sono familiari, collabora con una persona sviluppatrice.

Includere dati correlati in una risposta API

Quando un endpoint supporta il parametro di query include, la tua chiave deve avere l'autorizzazione per leggere sia la risorsa richiesta sia i dati correlati.

Ad esempio, GET /api/profiles/{id}/ recupera un profilo e richiede profiles:read. Sostituisci {id} con l’ID del profilo.

Per includere gli elenchi di questo profilo, usa GET /api/profiles/{id}/?include=lists con profiles:read e lists:read. L’endpoint della raccolta profili (GET /api/profiles/) non supporta l’inclusione di elenchi.

Preseleziona gli ambiti nella pagina di creazione

Aggiungi il parametro di query scopes all'URL di creazione della chiave API privata per preselezionare i livelli di accesso nel modulo.

Usa un elenco di nomi di ambito separati da virgole. Rivedi l’accesso selezionato, inserisci un nome per la chiave e seleziona Crea. Poi copia o scarica la chiave prima di chiudere la pagina di conferma.

Un URL di esempio è:
https://www.klaviyo.com/create-private-api-key?scopes=campaigns:read,campaigns:write

Vai al nostro portale di sviluppo per vedere gli ambiti che puoi usare in questa query.

Risorse aggiuntive