Uwierzytelnianie i klucze API

Skopiuj stronę

Tworzenie i cofanie kluczy API dla REST API i serwera MCP Workflow Transactional Email do Shopify Flow. Poziomy dostępu: odczyt, zapis, wykonywanie.

Zarówno interfejs API REST, jak i serwer MCP korzystają z tych samych danych uwierzytelniających: klucza API utworzonego na stronie Dla programistów w aplikacji.

Adres URL bazowy

Wszelkie wnioski należy kierować na adres:

text

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

Każdy z poniższych punktów końcowych odnosi się do tego hosta, więc pełna ścieżka do indeksu to https://shopify.workflow-transactional-email.app/api/v1.

Tworzenie klucza

Proszę uruchomić aplikację Developer, wybrać poziom dostępu i utworzyć klucz. Pełna wartość klucza jest wyświetlana tylko raz, w momencie jego utworzenia. Proszę ją wówczas skopiować i zapisać w menedżerze haseł lub magazynie tajnych danych - nie będzie można jej później odzyskać, ponieważ przechowywany jest jedynie jej skrót SHA-256.

Klucze zawsze zaczynają się od fak_, co ułatwia ich wykrycie za pomocą skanera haseł.

Proszę wysłać to jako token na okaziciela:

vbnet

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

GET /api/v1/me to najszybszy sposób na sprawdzenie, czy klucz działa, oraz na ustalenie, jaki poziom uprawnień zapewnia.

Poziomy dostępu

Poziomy są uporządkowane i mają charakter kumulatywny: każdy z nich obejmuje wszystkie poziomy znajdujące się poniżej niego.

Poziom	Co to wnosi
Tylko do odczytu	Odczytywanie układów wiadomości e-mail, nadawców wiadomości, ukrytych nazw, przesłanych plików, żądań HTTP, historii i statystyk
Odczyt i zapis	Tworzenie, edycja i usuwanie żądań HTTP oraz usuwanie nieużywanych plików, które zostały przesłane
Odczyt, zapis i wykonanie	Proszę wysłać żądanie HTTP do rzeczywistego adresata

Proszę zwrócić uwagę, jak wąskie są dwa górne poziomy. Wszystkie elementy związane z pocztą elektroniczną są tylko do odczytu, a żaden z nich nie jest dostępny do zapisu na żadnym poziomie - patrz poniżej.

Co klucz zapisu może zmienić, a czego nie może zmienić

Możliwości: tworzenie, edytowanie, usuwanie i uruchamianie żądań HTTP oraz usuwanie przesłanych plików, do których nie ma żadnych odwołań.

Nie można: wprowadzać żadnych zmian w elementach decydujących o tym, co otrzymują Państwa klienci. Układy wiadomości e-mail, nadawcy wiadomości oraz dane poufne nie posiadają punktu końcowego do zapisu na żadnym poziomie dostępu, a punkt końcowy służący do wysyłania wiadomości e-mail w ogóle nie istnieje. Wiadomość e-mail jest wysyłana w momencie, gdy proces w Shopify Flow uruchamia akcję Send Transactional Email (Wyślij wiadomość transakcyjną); API jedynie rejestruje to zdarzenie i generuje raport po jego zakończeniu.

Usunięcie pliku jest również niemożliwe, dopóki jakikolwiek szablon lub ustawienie wstępne nadal korzysta z tego pliku, więc klawisz zapisu nie może spowodować uszkodzenia aktywnej wiadomości e-mail poprzez usunięcie jej logo.

Jeśli muszą Państwo zmienić układ lub podłączyć nadajnik, proszę to zrobić w aplikacji.

Dlaczego funkcja „execute” jest oddzielna

Wysłanie żądania HTTP powoduje wysłanie rzeczywistego żądania do rzeczywistego systemu zewnętrznego. Oddzielenie tego procesu na osobnym poziomie oznacza, że klucz, który przekazują Państwo skryptowi - lub asystentowi AI - w celu odczytu i edycji konfiguracji, nie może powodować wysyłania żądań do Państwa aktywnych integracji.

Domyślnie należy przyznawać uprawnienia do odczytu. Uprawnienia do zapisu lub wykonywania należy przyznawać wyłącznie wtedy, gdy jest to konieczne w przypadku konkretnego zadania.

Sekrety nigdy nie są czytelne, na żadnym poziomie

Wartości poufne, nazwy użytkowników i hasła SMTP oraz tokeny połączonych skrzynek pocztowych nie mogą zostać odczytane za pośrednictwem żadnego z tych interfejsów. Ani za pomocą klucza zapisu, ani klucza wykonania, ani poprzez MCP. Nie istnieje żaden punkt końcowy ani narzędzie, które by je zwracało.

Zamiast tego otrzymują Państwo flagi hasValue, hasUsername i hasPassword oraz nazwy sekretów, co wystarcza, aby asystent mógł odwołać się do {{ secrets.stripeApiKey }}, nie mając w ogóle wglądu w samą wartość. Zawsze mogą Państwo ustawić nową wartość; nigdy nie można jednak odzyskać starej.

Praktyczna konsekwencja: wyciek klucza odczytu naraża na ujawnienie Państwa konfigurację, a nie dane uwierzytelniające.

Unieważnienie klucza

Proszę usunąć klucz na stronie Dla programistów. Unieważnienie zacznie obowiązywać przy następnym żądaniu - nie ma potrzeby oczekiwania na odświeżenie pamięci podręcznej.

Należy unieważnić i ponownie wygenerować klucz, jeśli został on umieszczony w repozytorium, wklejony do dokumentu udostępnionego innym osobom lub przekazany wykonawcy, który już go nie potrzebuje.

Dobre nawyki

W żądaniach HTTP prosimy o odwoływanie się do danych uwierzytelniających w postaci {{ secrets.KEY }}, zamiast wklejać je bezpośrednio do nagłówka lub treści żądania. Dane uwierzytelniające podane w postaci literałowej są maskowane w odpowiedziach API, jednak korzystanie z odwołania do klucza tajnego jest lepszym rozwiązaniem.
Proszę używać jednego klucza na każdego konsumenta, aby móc cofnąć pojedynczą integrację bez zakłócania działania pozostałych.
Prosimy o nieprzechowywanie kluczy wykonawczych na laptopach programistów ani w konfiguracjach asystentów AI, chyba że wyraźnie chcą Państwo, aby asystent mógł wysyłać żądania w czasie rzeczywistym.