非公開 API キーを作成または複製する方法

このページで学べること

API 呼び出しに使用する一意の識別子であるプライベート API キーを作成する方法と、スコープを定義する方法をご確認ください。

プライベート API キーとスコープの両方により、サードパーティがアクセスできる内容を制限することで、自社および顧客のデータを保護できます。

非公開 API キーとスコープについて

API 呼び出しを行うと、あるソフトウェアが別のソフトウェアに接続できるようになります。この接続により、あるソフトウェアが別のソフトウェアに対して情報のリクエスト、編集、または追加を行えるようになります。

プライベート API キーにより、このリクエストに適切な権限があること（つまり、承認されたユーザー、アカウント、またはプログラムから送信されたこと）が保証されます。家の鍵のようなものだと考えてください。あなたと家族を中に入れ、他の人は締め出します。

プライベート API キーにスコープを含めることで、追加の認可レイヤーが加わり、第三者がアクセスできる特定の要素を制限できます。スコープはホテルのキーのようなもので、建物全体ではなく、特定のエリア（客室やジムなど）にのみアクセスできます。

スコープの種類

プライベート API キーを作成する際は、そのスコープを選択する必要があります。つまり、サードパーティに次のことをさせるかどうかを決定する必要があります。

• API エンドポイントにアクセスできない。
• API エンドポイントのすべてのデータを表示できますが、変更は行えません（「読み取り専用」とも呼ばれます）。
• そのエンドポイントに関連付けられたあらゆるものを作成、削除し、その他の変更を行います（「フル アクセス」または「書き込みアクセス」とも呼ばれます）。

例えば、サードパーティのソフトウェアからKlaviyo リストに購読者を追加したいとします。その場合、リスト、プロファイル、およびプロファイルの一括購読の API エンドポイントに対する完全な（書き込み）アクセス権限が必要です。ただし、サードパーティは他のエンドポイントへのアクセスは必要ありません。

開発者ポータルで Klaviyo の API と、各エンドポイントで利用可能なスコープを確認できます。

始める前に

次の点にご注意ください。

• プライベート API キーを作成した後は、次の操作はできません。
  • プライベート API キーを再度表示します。
    • ヒント: プライベート API キーは安全に保存し、パスワードマネージャーなどに使用目的をメモしておきましょう。
  • そのスコープを追加または編集します。
    • スコープを変更する必要がある場合、選択肢は元のプライベート API キーを削除し、正しいスコープで新しいものを作成することだけです。
• 非公開 API キーはデフォルトでフルアクセス権を持ちます。

必要な API エンドポイント、スコープ、または権限がわからない場合は、開発者に連絡するか、Klaviyo パートナーに問い合わせてサポートを受けてください。

非公開 API キーを作成

1. 左下隅の組織名をクリックします。
2. [設定]に進みます。
3. [API キー] をクリックします。
   

4. [非公開 API キーを作成する] をクリックします。
5. API キーに名前を付けます。
6. API キーに付与するスコープを選択してください。
   • 読み取り専用
   • 全幅
   • カスタム

7. [作成] を選択します。

これで、非公開 API キーを共有する場合でも、サードパーティはスコープで定義した情報にのみアクセスできます。

クエリを使用する

クエリは高度なシナリオで使用されます。クエリやその使用方法にまだ慣れていない場合は、開発者と連携することをおすすめします。

含める

include クエリを使用しようとすると、上記に記載されている形式から変更する必要がある点にご注意ください。

たとえば、プロファイルのエンドポイントは /api/profiles です。

ただし、include クエリパラメーター（/api/profiles?include=list）を追加する場合は、実行する API 呼び出しの種類に応じて、list:read または list:full access も必要になります。

スコープ

scopes パラメータを使用すると、プライベート API キーに必要なアクセス範囲を自動入力するための URL パラメータを作成できます。

スコープ クエリに、事前選択したいスコープのカンマ区切りのリストを含めます。

URL の例は次のとおりです：
https://www.klaviyo.com/create-private-api-key?scopes=campaigns:read,campaigns:write

このクエリで使用できる スコープ を確認するには、開発者ポータルに移動してください。

非公開 API キーを複製する

プライベート API キーでは、複製により、元のキーと同じスコープと権限を持つ新しいキーを作成できます。

注意：

• クローンを作成しても、元のプライベート API キーと同じキーは生成されません。
• 複製した API キーの名前を変更することはできません。元のキーと同じ名前になります。

非公開 API キーを複製するには：

1. ［API キー］ タブに移動します。
2. 複製したいキーの横にある 3 点メニューをクリックします。
3. [複製] > [複製] を選択します。
   

4. 新しいプライベート API キーをコピーまたはダウンロードし、安全な場所に保管してください。
5. 不要になった古いキーは必ず削除してください。

その他のリソース