Autenticazione e chiavi API

Sia l'API REST che il server MCP utilizzano le stesse credenziali: una chiave API creata nella pagina "Sviluppatori" all'interno dell'app.

URL di base

Tutte le richieste vanno inviate a:

text

https://shopify.workflow-transactional-email.app

Ogni endpoint riportato di seguito è relativo a tale host; pertanto, il percorso completo dell’indice è https://shopify.workflow-transactional-email.app/api/v1.

Creazione di una chiave

Apra Developer nell'app, scelga un livello di accesso e crei la chiave. Il valore completo viene visualizzato una sola volta, al momento della creazione. Lo copi quindi e lo salvi nel Suo gestore di password o in un archivio di dati riservati: non potrà più essere recuperato in seguito, poiché ne viene conservato solo l'hash SHA-256.

Le chiavi iniziano sempre con fak_, il che le rende facili da individuare in uno scanner di segreti.

Lo invii come token al portatore:

vbnet

GET /api/v1/me HTTP/1.1
Host: shopify.workflow-transactional-email.app
Authorization: Bearer fak_your_key_here

GET /api/v1/me è il modo più rapido per verificare se una chiave funziona e per vedere a quale livello corrisponde.

Livelli di accesso

I livelli sono ordinati e cumulativi: ciascuno di essi comprende tutto ciò che si trova al di sotto di esso.

Livello	Cosa apporta
Solo lettura	Leggere i layout delle e-mail, i mittenti delle e-mail, i nomi segreti, i file caricati, le richieste HTTP, la cronologia e le statistiche
Lettura e scrittura	Creare, modificare ed eliminare richieste HTTP, nonché eliminare i file caricati non utilizzati
Lettura, scrittura ed esecuzione	Eseguire una richiesta HTTP indirizzata al suo destinatario effettivo

Si noti quanto siano ristretti i due livelli superiori. Tutto ciò che riguarda la posta elettronica è leggibile, ma nulla è modificabile, a nessun livello - come illustrato di seguito.

Cosa può e cosa non può modificare una chiave di scrittura

È possibile: creare, modificare, eliminare ed eseguire richieste HTTP, nonché eliminare i file caricati a cui non fa riferimento alcun elemento.

Non è possibile: modificare alcun elemento che determini il contenuto delle comunicazioni inviate ai clienti. I layout delle e-mail, i mittenti e le informazioni riservate non dispongono di alcun endpoint di scrittura a nessun livello di accesso, e non esiste affatto un endpoint per l’invio delle e-mail. Le e-mail vengono inviate quando il workflow di Shopify Flow esegue l’azione “Invia e-mail transazionale”; l’API si limita a registrare e riportare l’operazione a posteriori.

La cancellazione del file viene inoltre negata fintantoché un layout o un’impostazione predefinita ne fa ancora uso; pertanto, un tasto di scrittura non può compromettere un’e-mail attiva rimuovendone il logo.

Se ha bisogno di modificare un layout o di collegare un mittente, lo faccia nell'app.

Perché la funzione "execute" è separata

L'esecuzione di una richiesta HTTP comporta l'invio di una richiesta effettiva a un sistema di terze parti reale. Mantenere tale operazione all'interno di un livello separato significa che una chiave che fornite a uno script - o a un assistente di intelligenza artificiale - per la lettura e la modifica della configurazione non possa generare richieste verso le vostre integrazioni attive.

Assegnare per impostazione predefinita i diritti di lettura. Aggiungere i diritti di scrittura o di esecuzione solo quando un lavoro specifico li richiede.

I segreti non sono mai comprensibili, a nessun livello

I valori segreti, i nomi utente e le password SMTP, nonché i token delle caselle di posta collegate non possono essere recuperati tramite nessuna delle due interfacce. Né con una chiave di scrittura, né con una chiave di esecuzione, né tramite MCP. Non esiste alcun endpoint né alcuno strumento in grado di restituirli.

Si ottengono invece flag e nomi segreti del tipo hasValue, hasUsername e hasPassword, il che è sufficiente affinché un assistente possa fare riferimento a {{ secrets.stripeApiKey }} senza mai visualizzarne il valore. È sempre possibile impostare un nuovo valore; non è mai possibile recuperare uno precedente.

La conseguenza pratica: la divulgazione di una chiave di lettura espone la vostra configurazione, non le vostre credenziali.

Revoca di una chiave

Elimini la chiave nella pagina “Sviluppatore”. La revoca avrà effetto alla richiesta successiva: non è necessario attendere l’aggiornamento della cache.

Si prega di revocare e riemettere la chiave qualora questa sia stata inserita in un repository, incollata in un documento condiviso o fornita a un collaboratore esterno che non ne abbia più bisogno.

Buone abitudini

Nelle vostre richieste HTTP, fate riferimento alle credenziali come {{ secrets.KEY }} anziché incollarle nell'intestazione o nel corpo della richiesta. Le credenziali letterali vengono mascherate nelle risposte dell'API, ma è preferibile fare riferimento a un segreto.
Utilizzi una chiave per ogni utente, in modo da poter revocare una singola integrazione senza compromettere le altre.
Si raccomanda di non inserire le chiavi di esecuzione sui computer portatili degli sviluppatori né nelle configurazioni degli assistenti di intelligenza artificiale, a meno che non si desideri espressamente che l’assistente sia in grado di inviare richieste in tempo reale.