Kinsta APIで企業ユーザーとアクセス権限を管理

Kinsta API経由で、WordPressサイトへのユーザーのアクセス権限を管理できるようになりました。

今回新たに3つのエンドポイントが追加され、特定の企業ユーザーの詳細情報を取得したり、企業単位またはサイト単位でアクセス権限を変更したりできるようになりました。また、既存の企業ユーザー一覧取得用エンドポイントを拡張し、各ユーザーの役割や二要素認証（2FA）の方法に関する詳細情報も取得できます。

さらに、API操作が失敗した際、サポートへスムーズにお問い合わせいただけるよう、新たに参照IDも導入しました。

ユーザーの役割と二要素認証の設定情報を含む企業ユーザー一覧の取得

既存の企業ユーザー一覧を取得するエンドポイントが拡張され、各ユーザーについてより詳しい情報を取得できるようになりました。

これまでは、ユーザー名、メールアドレス、プロフィール画像などの基本情報を取得できましたが、今回の更新により、企業単位およびサイト単位でのユーザーの役割を示すcapabilities配列と、設定されている二要素認証（2FA）の方法を示すtype_2faフィールドもレスポンスに含まれるようになりました。

企業ユーザーの一覧を取得するには、以下のGETリクエストを送信します。

curl --request GET 
  --url https://api.kinsta.com/v2/company/{company_id}/users 
  --header 'Authorization: Bearer <YOUR_TOKEN_HERE>'

レスポンスには、新たに以下のフィールドが含まれるようになります。

{
  "company": {
    "users": [
      {
        "user": {
          "id": "54fb80af-576c-4fdc-ba4f-b596c83f15a1",
          "email": "[email protected]",
          "image": "https://www.gravatar.com/avatar/205e460b479e2e5b48aec07710c08d50",
          "full_name": "John Doe",
          "type_2fa": "email"
        },
        "capabilities": [
          {
            "id": "9c1f7b2e-3d4a-4f5b-8c6d-1e2f3a4b5c6d",
            "type": "company",
            "role": "company-admin",
            "company_id": "54fb80af-576c-4fdc-ba4f-b596c83f15a1",
            "site_id": null
          }
        ]
      }
    ]
  }
}

capabilities配列の各要素には、ユーザーに割り当てられた役割と、その役割が適用される企業またはサイトの情報が含まれます。type_2faフィールドには、設定されている二要素認証の方法が返され、未設定の場合はnullになります。

これらの情報は、ユーザーのアクセス権限や割り当てられた役割の確認、特定のリソースにアクセスできるユーザーを表示する社内ツールの開発などに便利です。

IDを指定して特定の企業ユーザーの情報を取得

IDを指定して企業ユーザーを取得するエンドポイントを使用すると、企業ユーザーの一覧全体を取得することなく、特定のユーザーの詳細情報を取得できます。

リクエストには、企業IDとユーザーIDを指定します。

curl --request GET 
  --url https://api.kinsta.com/v2/company/{id}/users/{id_user} 
  --header 'Authorization: Bearer <YOUR_TOKEN_HERE>'

レスポンスには、対象ユーザーの基本情報、二要素認証の方法、割り当てられた役割やアクセス権限の情報が含まれます。

{
  "company": {
    "user_by_id": {
      "user": {
        "id": "9c1e4d2a-1b3c-4f5a-8d6e-7f8a9b0c1d2e",
        "email": "[email protected]",
        "full_name": "John Doe",
        "type_2fa": "email"
      },
      "capabilities": [
        {
          "role": "company-developer",
          "id_company": "54fb80af-576c-4fdc-ba4f-b596c83f15a1",
          "id_site": null
        }
      ]
    }
  }
}

このエンドポイントは、ユーザーの役割を変更する前に現在のアクセス権限を確認したり、社内向けのアクセス権限レポートに特定のユーザーの権限情報を含めたりする際に役立ちます。

企業ユーザーの役割の変更

企業ユーザーのアクセス権限を変更するエンドポイントを使用すると、既存ユーザーの企業単位での役割を変更できます。

以下の3つの役割に対応しています。

• company-admin（企業の管理者）：企業全体の管理アクセス権を持つ
• company-developer（企業の開発者）：請求関連の権限を除き、サイトおよび開発関連リソースを管理するためのアクセス権限を持つ
• company-billing（企業の経理係）：WordPressサイトへのアクセス権は持たないが、請求情報へのアクセス権を持つ

例えば、以下のリクエストを送信すると、既存ユーザーの役割を「企業の開発者（Company Developer）」に変更できます。

curl --request POST 
  --url https://api.kinsta.com/v2/company/{company_id}/users/company-capabilities 
  --header 'Authorization: Bearer <YOUR_TOKEN_HERE>' 
  --header 'Content-Type: application/json' 
  --data '{
    "user_id": "54fb80af-576c-4fdc-ba4f-b596c83f15a1",
    "role": "company-developer"
  }'

リクエストが受け付けられると、レスポンスには操作IDが含まれます。

{
  "message": "User capabilities updated for the company",
  "status": 202,
  "operation_id": "company:set-company-user-capabilities-54fb80af-576c-4fdc-ba4f-b596c83f15a1"
}

返されたoperation_idを使用して、操作の実行状況を確認できます。

企業単位の役割によって、ユーザーがアクセスできるリソースが決まります。そのため、役割を変更すると、サイト、請求情報、企業設定などへのアクセス権限が付与または削除される場合があります。各役割に付与されるアクセス権限については、ユーザーの役割と権限に関するドキュメントをご覧ください。

サイト単位でのユーザーのアクセス権限の変更

サイト用のユーザー機能を編集するエンドポイントを使用すると、サイト単位でのアクセス権限も管理できます。

企業単位のアクセス権限とは異なり、サイト単位の権限は特定のWordPressサイトにのみ適用されます。企業全体へのアクセス権限を付与せずに、開発者やクライアントに特定のサイトへのアクセスを許可したい場合に便利です。

このエンドポイントでは、user_ids配列とsite_capabilities配列を指定できるため、1回のリクエストで複数のユーザーとサイトへのアクセス権限をまとめて設定できます。

サイト単位では、以下の2つの役割を割り当てることができます。

• site-admin（サイトの管理者）：役割に応じた制限の範囲内で、割り当てられたサイトとその各環境を管理できるサイトの管理者

• site-developer（サイトの開発者）：サイトのステージング環境にアクセスできる、権限が制限されたサイトの開発者

例えば、以下のリクエストを送信すると、ユーザーに「サイトの開発者（Site Developer）」の役割を割り当てることができます。

curl --request POST 
  --url https://api.kinsta.com/v2/company/{company_id}/users/site-capabilities 
  --header 'Authorization: Bearer <YOUR_TOKEN_HERE>' 
  --header 'Content-Type: application/json' 
  --data '{
    "user_ids": [
      "54fb80af-576c-4fdc-ba4f-b596c83f15a1"
    ],
    "site_capabilities": [
      {
        "site_id": "54fb80af-576c-4fdc-ba4f-b596c83f15a1",
        "role": "site-developer"
      }
    ]
  }'

レスポンスには、更新処理の進行状況を確認するための操作IDが含まれます。

{
  "message": "Users capabilities updated for the site",
  "status": 202,
  "operation_id": "company:set-site-user-capabilities-54fb80af-576c-4fdc-ba4f-b596c83f15a1"
}

複数のクライアントサイトを管理するWeb制作会社などでは、このエンドポイントを活用することで、オンボーディング用のスクリプトや社内の管理システムから、各サイトへのアクセス権限を割り当てることができます。

サポート参照IDを使用したAPI操作のトラブルシューティング

MyKinstaでの操作を実行するAPIエンドポイントのレスポンスに、オプションのsupport_reference_idフィールドも追加しました。

これまでは、レスポンスに含まれるoperation_idを使用して、操作の進行状況を確認できました。しかし、操作IDは一時的にキャッシュされる仕組みのため、リクエストが失敗した際に、元の操作を特定するのが難しい場合がありました。

新たに導入されたsupport_reference_idは、元の操作を識別するためのIDです。これにより、Kinstaのサポートスタッフが問題の原因をよりスムーズに調査できるようになります。

このフィールドは、最初のAPIレスポンスに加え、既存の操作のステータスを取得するエンドポイントで操作状況を確認した際のレスポンスにも含まれる場合があります。

curl --request GET 
  --url https://api.kinsta.com/v2/operations/{operation_id} 
  --header 'Authorization: Bearer <YOUR_TOKEN_HERE>'

例えば、操作がまだ実行中の場合、以下のようなレスポンスが返されます。

{
  "status": 202,
  "message": "Operation in progress",
  "support_reference_id": 12345,
  "data": null
}

API操作が失敗した場合は、サポートへの問い合わせ時にサポート参照IDを伝えることで、担当者が該当する操作を特定し、問題の原因を調査しやすくなります。

support_reference_idは任意のフィールドであるため、外部連携では引き続きoperation_idを使用して操作の進行状況を追跡し、support_reference_idが返された場合は、その値も保存しておくことをおすすめします。

独自のツールからユーザーのアクセス権限を管理

今回追加された機能により、Kinsta APIを活用したユーザーのアクセス権限管理をさらに効率化できます。ユーザーの現在のアクセス権限の確認、企業単位での役割の変更、サイト単位でのアクセス権限の割り当てなどを、MyKinstaの画面から一つひとつ操作することなく実行できます。

また、新たに導入されたサポート参照IDを記録しておくことで、API操作のログ管理やエラー発生時の原因調査にも役立てることができます。

利用可能なエンドポイントやリクエスト形式については、Kinsta APIドキュメントをご覧ください。