Workflow Transactional EmailWorkflow Transactional Email

認証とAPIキー

REST API と MCP サーバーは、どちらも同じ認証情報を使用します。それは、アプリ内の「**開発者」**ページで作成された API キーです。

ベースURL

すべてのお問い合わせは、以下の宛先までお願いいたします：

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

以下の各エンドポイントはすべてそのホストを基準としているため、インデックスのフルパスは https://shopify.workflow-transactional-email.app/api/v1 となります。

鍵の作成

アプリで「Open Developer」を開き、アクセスレベルを選択して、キーを作成してください。完全な値は**、作成時に一度だけ**表示されます。その際にコピーして、パスワードマネージャーやシークレットストアに保存してください。その後、この値は復元できません。保存されるのはSHA-256ハッシュのみだからです。

鍵は常に「fak_」で始まるため、秘密スキャナーで簡単に見つけられます。

ベアラー・トークンとして送信してください：

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

GET /api/v1/me これは、キーが機能するかどうかを確認し、どのレベルに対応しているかを確認するための最も手っ取り早い方法です。

アクセス権限

レベルは順序付けられており**、累積的です**。つまり、各レベルにはその下のすべてのレベルが含まれています。

レベル 追加される機能
読み取り専用 メールのレイアウト、送信者、非表示名、アップロードされたファイル、HTTPリクエスト、履歴、および統計情報を読み取ります
読み取りと書き込み HTTPリクエストの作成、編集、削除、および使用されていないアップロード済みファイルの削除を行います
読み取り、書き込み、実行 実際のターゲットに対してHTTPリクエストを実行する

上部の2つのレベルがいかに狭いかにご注目ください。メールに関連するすべての項目は読み取り可能ですが、どのレベルにおいても書き込み可能な項目は一切ありません。詳細は以下をご覧ください。

なぜ「execute」が別になっているのか

HTTPリクエストを実行すると、実際のサードパーティシステムに対して実際のリクエストが送信されます。これを独自のレイヤーの背後で処理することで、設定の読み取りや編集のためにスクリプトやAIアシスタントに渡すキーが、本番環境の連携先に対してリクエストを送信してしまうことを防ぐことができます。

デフォルトでは読み取り権限のみを付与してください。書き込み権限や実行権限は、特定のジョブで必要となる場合にのみ追加してください。

鍵の失効

「開発者」ページでキーを削除してください。無効化は次のリクエストから有効になります。キャッシュによる遅延はありません。

鍵がリポジトリにコミットされた場合、共有ドキュメントに貼り付けられた場合、またはもはやその鍵を必要としない請負業者に渡された場合は、その鍵を取り消し、再発行してください。

良い習慣

  • HTTPリクエストでは、認証情報をヘッダーや本文に直接貼り付けるのではなく、{{ secrets.KEY }} のように参照形式で指定してください。APIのレスポンスでは、文字列として記述された認証情報はマスクされますが、シークレットを参照する方が望ましいです。
  • コンシューマーごとに1つのキーを使用してください。そうすれば、他の統合に影響を与えることなく、特定の統合のみを無効にすることができます。
  • 開発者のノートパソコンやAIアシスタントの設定から、実行キーを削除しておいてください。ただし、アシスタントにリアルタイムのリクエストを実行させたい場合はこの限りではありません。