メインコンテンツまでスキップ

複数事業者APIキーに関する補足

このドキュメントでは、1つのAPIキーで複数の事業者のAPIにアクセスできる複数事業者APIキーの概要を説明します。

ただし、複数事業者APIキーが必要となる場面は限定的であるため、APIキーによる認証の概要やAPIキーによる認証のチュートリアルにおける説明や手順は、原則として通常のAPIキー（後述する単一事業者APIキー）を前提としています。

「1つのAPIキーで複数の事業者のAPIにアクセスする」という要件がない場合は、通常のAPIキーを利用してください。

単一事業者APIキーと複数事業者APIキー​

アプリポータルで発行できるAPIキーには次の2種類があります。

APIキーの種類発行できるユーザーの条件APIキーがアクセスできる情報の範囲
単一事業者APIキー1つの事業者に所属し、その事業者のアプリポータルにユーザーとして追加されている発行時にログインしていた1事業者において、発行したユーザーの権限でアクセスできる情報
複数事業者APIキー2つ以上の事業者に所属し、そのいずれかまたはすべての事業者のアプリポータルにユーザーとして追加されている発行時に選択した複数の事業者それぞれにおいて、発行したユーザーの権限でアクセスできる情報

複数事業者APIキーの想定される用途​

複数事業者APIキーは、「1つのAPIキーで、発行したユーザーが所属する複数の事業者のAPIにアクセスしたい」場合に利用を検討してください。

たとえば、同一のクライアントで複数の事業者のデータを扱う連携で、事業者を切り替える度に認証（APIキーからJWTへの交換）をおこなわずに連続で処理したい、といった要件がある場合に選択肢となります。

一方、1つの事業者のデータのみを扱う連携であれば、通常のAPIキー（単一事業者APIキー）の方が認証の範囲が明確になり、運用も単純になることが多いです。 実際に複数事業者APIキーが必要かどうかは、連携の要件やクライアントの仕様に合わせて判断してください。

複数事業者APIキーのライフサイクル​

複数事業者APIキーを発行・利用するユーザーは、発行時に選択する事業者において管理コンソールに登録されたユーザーである必要があります。

複数事業者APIキーを発行したユーザーが、退会や削除により発行時に選択した事業者において管理コンソールに存在しなくなる場合、当該のAPIキーは削除または当該の事業者との関連付けが解除されます。

1. APIキーと事業者との関連付けの変化​

発行時に選択した事業者における発行者（APIキーを発行したユーザー）の状態に応じて、APIキーとその事業者との関連付けは以下のとおり連動して変化します。

事業者の管理コンソールにおける発行者の状態事業者のアプリポータルにおける発行者の状態APIキーとその事業者との関連付け
登録されている登録されている有効
登録されている登録されていない有効
登録されている事業者の管理者により削除された有効
登録されているアプリポータルが利用終了され、それに伴い削除された無効
事業者の管理者により削除された管理コンソールからの削除に伴い削除された無効
マネーフォワード IDの退会により削除された管理コンソールからの削除に伴い削除された無効
事業者が利用停止され、それに伴い停止された管理コンソールの停止に伴い停止された無効

2. APIキーの状態の変化​

事業者とAPIキーの関連付けが無効になる場合、APIキーの状態は以下のとおり連動して変化します。

APIキーと各事業者との関連付け各事業者のアプリポータルにおける発行者の状態APIキーの状態
一部の関連付けが無効になったが、他は有効なまま1つ以上の事業者において登録されている保持される
一部の関連付けが無効になったが、他は有効なままどの事業者においても登録されていない削除される
すべての関連付けが無効になった─削除される

複数事業者APIキーの留意点​

1. 利用可能サービスの制約​

複数事業者APIキーをアプリポータルで発行する際、「利用可能サービス」と「利用可能事業者」を選択しますが、これは「選択したすべてのサービスのAPIに対して選択したすべての事業者でアクセス可能になる」という意味ではありません。

複数事業者APIキーで実際にアクセス可能になるサービスは、各事業者のサービスの契約/利用状況に依存するため、複数事業者APIキーを発行する際に選択したサービスのAPIであっても事業者によってアクセス不可能（401）となる場合があります。

2. セキュリティ上の注意事項​

  • APIキーでアクセス可能な事業者は発行時に選択したものに限られるため、APIキー発行時に不要な事業者を選択しないようにしてください。不要な事業者を含めたままにすると、APIキーでアクセス可能な事業者の範囲が不必要に広がります。
  • 最小権限の原則は、複数事業者APIキーでも変わりません。APIキー発行時に指定する利用可能サービスや利用可能事業者、またマネーフォワード クラウドの各サービスにおいてユーザーに付与する権限とあわせて、必要な範囲に収めてください。
注意

複数事業者APIキーは、通常のAPIキー（単一事業者APIキー）と同様、長期的な認証情報（クレデンシャル）です。

取り扱いはパスワードと同じように厳重に行い、ソースコードへのハードコードやバージョン管理へのコミットは避けてください。

詳細はAPIキーによる認証のセキュリティ上の注意事項を参照してください。

次のステップ​

APIキーの概念を理解したら、目的に応じて次のドキュメントを参照してください。

目的次のステップ
アプリポータルにおけるAPIキーの役割と主な機能を知りたいアプリポータルの概要（APIキー）
APIキー発行権限を安全に運用したいアプリポータルの権限設計のベストプラクティス（APIキー）
APIキーの発行からJWTの取得・実装までを段階的に学びたいチュートリアル: APIキーによる認証
/auth/exchangeエンドポイントの技術仕様を確認したいAPIリファレンス: /auth/exchange
OAuth 2.0による認可の概要やAPIキーとの違いを知りたいOAuth 2.0による認可