アプリポータルの概要（APIキー）
1. 導入
このドキュメントでは、APIキーによる認証を利用する方を対象に、「アプリポータル」の役割・主な機能・権限の仕組みを説明します。APIキーの基本的な概念についてはAPIキーによる認証を、アプリポータルのUI操作についてはアプリポータルの使い方ガイドを参照してください。
2. アプリポータルとは
APIキーによる認証を利用するには、アプリポータルの利用が必須です。
アプリポータルは、マネーフォワード クラウドのAPI連携に必要な認証情報の発行やユーザー権限の管理を担う管理基盤です。APIキーは、アプリポータルに登録されたユーザーに紐づけて発行され、アクセス対象となるサービスを指定して作成します。
アプリポータルの登録および利用は無料です。
アプリポータルでの「アプリ」とは、マネーフォワード クラウドのAPIを利用するために必要な認証情報をまとめた登録単位です。ただし、APIキーの場合、アプリではなくユーザーに紐づけてAPIキーを発行します。
3. エコシステムの全体像
APIキーによるAPI連携には、以下のコンポーネントが関与します。
| コンポーネント | 役割 |
|---|---|
| 開発者のアプリケーション | APIキーで取得したJWTを使用してマネーフォワード クラウドのAPIを呼び出す |
| アプリポータル | API連携の管理基盤。APIキーの発行・権限設定を担う |
| 認証サーバー | APIキーをJWTに交換する /auth/exchange エンドポイントを提供 |
| マネーフォワード クラウド API | 会計・経費・給与など各サービスのAPIエンドポイント |
アプリポータルが関与するのは主にAPI連携の 準備段階（権限設定・APIキーの発行） です。一度設定が完了すれば、API呼び出しにアプリポータルの操作は不要です。
4. APIキー連携における権限の仕組みと登場人物
登場人物と役割
APIキー発行には、以下の役割が関与します。
| 役割 | 誰か | 主な操作 | 関与するタイミング |
|---|---|---|---|
| 全権管理者 | マネーフォワード クラウドの管理コンソールで全権管理権限を持つユーザー | アプリポータルの利用開始・初期設定 | 初回のみ |
| システム管理者 | アプリポータルの管理者 | ユーザー招待・権限付与 | 初回設定時・体制変更時 |
| アプリ開発者 | API連携を開発するエンジニア | APIキーの発行 | 開発時 |
APIキーはユーザーの権限でAPIを実行するため、OAuthのような「連携管理者」による認可操作は不要です。ただし、APIキーの発行権限の管理は重要です。詳しくは権限設計のベストプラクティスを参照してください。
APIキー発行の仕組み
- APIキーはユーザーに紐づけて発行される: アプリポータルに登録されたユーザーが自身のAPIキーを発行します。発行されたAPIキーは、指定したサービスの範囲内で、発行したユーザーの権限でAPIを実行できます。
- APIキー発行はアプリポータルの権限に基づく: APIキーを発行するには「アプリ開発」権限が必要です。発行されたAPIキーは、そのユーザーがマネーフォワード クラウドの各サービスで持つ権限の範囲でAPIを実行します。
APIキー連携の全体フロー
APIキー連携は、以下のフローで進みます。
| ステップ | 担当 | 操作 | 頻度 |
|---|---|---|---|
| 1. 利用開始 | 全権管理者 | アプリポータルの利用を開始する | 初回のみ |
| 2. 権限付与 | システム管理者 | ユーザーを招待し、権限を付与する | 初回・体制変更時 |
| 3. APIキー発行 | アプリ開発者 | APIキーを発行し、安全に保管する | 開発時 |
| 4. API呼び出し | 開発者のアプリ | APIキーでJWTを取得し、APIを呼び出す | 日常運用 |
5. 主な機能
アプリポータルには、APIキー連携の管理に必要な以下の機能があります。
ユーザー管理
アプリポータルを利用するユーザーと、その権限を管理します。
| 権限 | 説明 |
|---|---|
| システム管理者 | アプリポータル全体の管理（ユーザーの招待・削除、全権限の設定） |
| アプリ開発 | APIキーの発行・無効化 |
| アプリ連携 | APIキーには直接関係しない。OAuth認可におけるサービスとアプリの連携操作 |
APIキー発行には「アプリ開発」権限が必要です。権限の詳細は「権限」の設定方法を参照してください。
APIキー管理
発行したAPIキーの一覧確認と無効化を行います。
- APIキーの発行
- 発行済みAPIキーの確認
- APIキーの無効化
社内システムとマネーフォワード クラウドを連携するケースでは、アプリポータルの各機能を以下のように使用します。
- ユーザー管理: システム管理者が、APIキーを発行する開発者に「アプリ開発」権限を付与する
- APIキー管理:「アプリ開発」権限を持つ開発者がAPIキーを発行し、社内システムで使用する
6. アプリポータルの制約
個人単位のアクセス制御
APIキーは発行したユーザーにマネーフォワード クラウドの各サービスで付与されている権限でAPIを実行します。そのため、OAuthと異なり、事業者全体ではなく特定のユーザーの権限範囲に限定されます。
たとえば、OAuthと比較して次のような特徴があります。
- 経理部門の管理者としての権限を持つユーザーがAPIキーを発行した場合、そのAPIキーで操作できるデータは、経理部門の管理者がマネーフォワード クラウドの画面（UI）上で閲覧・操作できる範囲に限られる
- OAuthで認可されたアプリは、事業者に登録された全従業員・全部門のデータなど、事業者全体のデータにアクセスできる
- APIキーは、発行したユーザーが持つマネーフォワード クラウドの各サービスで付与されている権限をそのまま引き継ぐため、アクセス範囲をユーザー単位で制御したい場合に適している
サービス単位での権限設定
APIキー発行時には、アクセスを許可するサービスを指定します。必要最小限のサービスのみを選択してください。
サービスによっては追加の権限設定が必要な場合がある
APIキー発行にはアプリポータルの「アプリ開発」権限が必須ですが、サービスによっては、そのサービスや関連サービス上でのユーザー権限が別途必要になる場合があります。必要な権限の詳細はサービスごとに異なります。 詳しくは、サービスごとの権限設定の方法をご確認ください（例：APIを利用するために必要な設定を教えてください（従業員と組織））。
7. 利用開始するには
前提条件
- マネーフォワード クラウドで事業者を作成済みであること（事業者区分や契約プランは問いません）
- マネーフォワード クラウドの管理コンソールで「全権管理者」の権限を持つユーザーがいること（初回利用開始時）
利用開始の手順
以下の手順のうち、ステップ1・2は事業者の 全権管理者 が行います。ステップ3は 「アプリ開発」権限を持つユーザー が行います。
-
アプリポータルの利用を開始する（全権管理者） 管理コンソールの全権管理者がアプリポータルの利用を開始します。 ▶ 「アプリポータル」の利用開始方法
-
ユーザーの権限を設定する（全権管理者） API連携を担うユーザーに必要な権限を付与します。 ▶ 「権限」の設定方法
-
APIキーを発行する（アプリ開発権限を持つユーザー） APIキーを発行します。
8. 次のステップ
アプリポータルの概要を理解したら、ご自身の立場に応じて以下のドキュメントに進んでください。
| 立場 | 次のステップ |
|---|---|
| 初めてアプリポータルを導入したい（全権管理者） | 「アプリポータル」の利用開始方法 |
| APIキーを実際に使ってみたい（開発者） | チュートリアル: APIキーによる認証 |
| 権限設計を検討したい（システム管理者） | 権限設計のベストプラクティス |
| アプリポータルのUI操作を知りたい | アプリポータルの使い方ガイド |