APIクライアント
APIクライアントを使用すると、各エンドポイントへのアクセスを設定できる複数のクライアントを作成して、セキュリティのベストプラクティスを適用できます。 APIクライアントリクエストでは、認証に単一のヘッダーが必要です。
APIクライアントは、個々のユーザーではなくワークスペースレベルでスコープ設定されます。 つまり、作成した個々のユーザーとは関係なく、割り当てられたクライアントロールで定義された権限に従って動作します。
レガシーフルアクセスAPIキー
APIクライアント以前は、WorkatoのAPIは、リクエストヘッダーまたはクエリパラメーター内のレガシーフルアクセスAPIキーとメールを使用してリクエストを認証していました。 このレガシー機能は引き続きサポートされていますが、認証にはAPIクライアントへ移行することを強くお勧めします。 詳細を見る
移行は削除とは異なることに注意してください。 レガシーAPIクライアントを削除すると、APIキーとメールは復元できなくなり、このAPIキーとメールを使用するリクエストは拒否されます。
APIクライアントのメリット
WorkatoのDeveloper APIおよびEmbedded APIを使用すると、Developmentからプロダクションへのレシピマニフェストのデプロイや、ネットワーク環境内での新しいオンプレミスエージェントのデプロイなど、Workatoワークスペースを自動化できます。 APIクライアントを使用すると、各アプリケーションのユースケースに固有のAPIアクセスをプロビジョニングして、組織のセキュリティを向上できます。
APIクライアントと割り当て可能なロールを使用すると、APIアクセスをさまざまなレベルでスコープ設定できます:
- APIクライアントには、操作可能なAPIエンドポイントを定義するロールが割り当てられます。
- APIクライアントには、API呼び出しが許可されるEnvironment（DEV、TEST、PRODなど）が割り当てられます。 Environmentは特定の料金プランの顧客が利用でき、ワークスペースでは利用できない場合があります。
- APIクライアントにはプロジェクトが割り当てられます。 これにより、APIアクセスはそれらのプロジェクト内の特定のアセットに制限されます。
ワークスペース内のAPIエンドポイントおよびさまざまなプロジェクトに固有の個別クライアントを作成できます。 Workato Developer APIクライアントトークンは、Github Secret Scanningと統合されています。
クライアントロールの作成
APIクライアントを作成する前に、クライアントロールを作成する必要があります。 クライアントロールでは、APIクライアントがアクセスできるエンドポイントを設定できます。
クライアントロールを作成するには:
Workatoアカウントにサインインします。
ワークスペース管理者に移動します。
APIクライアント＞クライアントロール＞クライアントロールを追加を選択します。 
新しいクライアントロールの作成
新しいクライアントロールの名前を入力します。 たとえば、レシピAPIエンドポイントを操作できるロールには、"Recipe Operator"と入力します。
各セクションで、ロールに必要なエンドポイントを選択します。 ワークスペースで利用可能なすべてのWorkato APIエンドポイントが、これらのセクションに一覧表示されます。 
有効化する予定のエンドポイントを選択
選択が完了したら、ロールを保存します。 必要に応じて、後でクライアントロールを編集できます。
APIクライアントを作成する
APIクライアントを作成するには、次の手順を完了します:
ワークスペース管理者に移動します。
APIクライアント＞APIクライアントを作成を選択します。
新しいAPIクライアントの作成
目的がわかる新しいクライアントの名前を入力します。 たとえば、Sales and MarketingチームがAPIを通じてレシピを操作するために使用するAPIクライアントには、"Sales and Marketing - Recipe Operator"と入力します。
適切なクライアントロールを選択します。 クライアントロールは、APIクライアントがアクセスできるエンドポイントを決定します。
ワークスペースでEnvironmentが有効になっている場合は、APIクライアントがアクセスを許可されるEnvironmentを選択します。
APIクライアントがアクセスを許可されるプロジェクトを選択します。 このAPIクライアントを使用するチームに関連するプロジェクトのみを選択します。 プロジェクトアクセスルールは、connections、recipes、folders、lookup tables、properties、API Platform collections、API Platform API Clientsなど、プロジェクトにスコープ設定できるすべてのアセットに適用されます。
WARNING
Embedded APIへのアクセス権を持つEmbeddedパートナー向けAPIクライアントは、すべての顧客ワークスペースとプロジェクトにアクセスできます。
必要に応じて、このトークンを使用するAPIリクエストの発信元として許可する許可IP範囲を追加します。 静的サーバーからAPIを呼び出す場合、これによりWorkatoのDeveloper APIへのアクセスをさらに保護できます。
APIクライアントの作成後に表示されるAPIトークンを保存し、AWS Secrets Managerなどの安全な場所に保管します。 APIトークンを再度取得することはできません。
設定が完了したら、APIクライアントを保存します。 必要に応じて、後でAPIクライアントを編集できます。
新しい一度だけ表示されるAPIトークン
クライアントロールの編集
クライアントロールに対する編集は直ちに適用されます。
APIクライアントロールを編集するには:
ワークスペース管理者に移動します。
APIクライアント＞クライアントロール＞を選択し、編集するクライアントロールを選択します。
クライアントロールに権限を追加または削除し、かつ/またはプロジェクトアクセスを編集します。 これにより、関連付けられたAPIクライアントからのすべての受信APIリクエストに直ちに影響します。
変更を保存します。
APIクライアントの編集
APIクライアントに対する編集は直ちに適用されます。
APIクライアントを編集するには:
ワークスペース管理者に移動します。
APIクライアント＞を選択し、編集するAPIクライアントを選択します。
クライアントロールを変更し、かつ/またはプロジェクトアクセスを編集します。 これにより、関連付けられたAPIクライアントからのすべての受信APIリクエストに直ちに影響します。
変更を保存します。
APIクライアントトークンの更新
APIクライアントを作成した後、既存のクライアントに対して新しいAPIトークンを再生成できます。 APIクライアントトークンを更新するには:
ワークスペース管理者に移動します。
APIクライアント＞を選択し、編集するAPIクライアントを選択します。
ページの右上隅にある更新アイコンを選択します。
APIクライアントトークンを更新するための更新アイコンの選択
APIトークンを再生成モーダルで、トークンを再生成を選択します。 APIトークンを再生成すると、以前のAPIトークンを使用するAPI呼び出しは失敗します。
新しいAPIトークンをAWS Secrets Managerなどの安全な場所に保管します。 このAPIトークンを再度取得することはできません。
完了を選択して、APIクライアントの編集に戻ります。
新しいトークンを生成すると、以前のAPIトークンは無効になります。 レガシーAPIクライアントトークンは再生成できません。
カスタムスクリプトやアプリケーションで、GitHubのパブリックリポジトリやドキュメントなどの公開Webサイトにトークンをプレーンテキストでアップロードすると、ユーザーエラーによりトークンが漏えいする可能性があります。
APIクライアントまたはクライアントロールの削除
APIクライアントまたはクライアントロールを削除するときは注意してください。
削除されたAPIクライアント: 削除されたAPIクライアントのAPIトークンを使用するすべての受信リクエストは拒否されます。
削除されたクライアントロール: 関連付けられたAPIクライアントからのすべての受信リクエストは拒否されます。
APIクライアントとクライアントロールの管理に関するFAQ
1. クライアントロールはどのように設定すればよいですか。
クライアントロールは、ユースケースを考慮して設定する必要があります。 たとえば、"Recipe Operator"クライアントロールにはレシピの開始/停止を行うエンドポイントアクセスを付与し、"Project Deployment"クライアントロールにはレシピライフサイクルマネジメントおよびEnvironment propertiesエンドポイントへのアクセスを付与できます。 これをAPIクライアントレベルでのプロジェクトスコープ設定と組み合わせて使用することで、ユースケースとプロジェクトの両方にスコープ設定されたアクセスを実現できます。
ベストプラクティスとして、クライアントロールを定義する際には最小権限の原則を採用する必要があります。
2. APIクライアントはどのように設定すればよいですか。
ユースケースとプロジェクトを考慮してAPIクライアントを設定します。 たとえば、"Sales and Marketing - Recipe Operator" APIクライアントは、Sales and Marketingチーム専用にプロビジョニングできます。 APIクライアント設定では、権限を定義するときに具体的に指定できるためセキュリティが向上しますが、管理するAPIトークンが増えるため複雑さも増します。
3. APIクライアントトークンはどこに保管すればよいですか。
APIクライアントトークンは一度だけ表示されるため、置き忘れると永久に失われます。 APIクライアントを復旧するには、トークンを再生成する必要があります。
APIトークンは、アクセスが制御された安全な場所に保管してください。 特に異なるチーム向けに複数のトークンを生成する予定がある場合は、これらのトークンを管理する方法としてAWS Secrets Managerのようなツールの利用を検討することをお勧めします。
4. 誰がAPIクライアントにアクセスでき、どのようにアクセスを制御できますか。
ワークスペース内のすべてのEnvironment管理者はAPIクライアントにアクセスできます。 Environment adminおよびレガシーAdminロールには、Developer APIおよびAPI platform権限があります。 ユーザーをAdminsとして追加するときは注意してください。ユーザーはAPIクライアントを作成、編集、削除できるため、WorkatoのAPIを使用する既存の自動化ワークフローに影響する可能性があります。
チームでカスタムロールを作成する場合、ワークスペース管理者セクションでAPIクライアントを選択して、APIクライアントへのアクセスを定義できます。 このカスタムロールを割り当てられたユーザーは、APIクライアントツールへのフルアクセス権を持ちます。
5. 一部のエンドポイントが"TEST"および"PROD" Environmentで互換性がないのはなぜですか。
Workatoの特定のAPIエンドポイントは、"Project deployments"や"Workspace Collaborators"など、"DEV" Environmentでのみ使用できます。 これは、これらのツールを"DEV" Environmentからのみ管理できるためです。
Last updated: