STEP 2. アクセストークンを取得する

STEP1で登録したアプリ情報（Client IDとClient Secret）を利用して、アクセストークンを取得します。

注記

マネーフォワードクラウドのAPIは、OAuth2.0という認可の仕組みを採用しています。
OAuth2.0では、アプリがデータを取得するために、ユーザーのIDやパスワードのかわりに、アクセストークンを利用します。これによりユーザーは自分のIDやパスワードをアプリケーションに教える必要がなくなり、セキュリティが向上します。また、アクセストークンには有効期限があるため、万一トークンが漏洩しても、被害を最小限に抑えられます。

ユーザーへ連携権限の付与

アクセストークンを取得するためには、アプリポータルの画面から「アプリ連携権限」の付与が必要です。

「アプリ連携権限」を付与されたユーザーは、指定したマネーフォワードクラウドのサービスや機能とアプリを連携する操作（アクセストークンの発行）ができます。

詳しくは「アプリポータル」権限の設定方法のページもご覧ください。

注意

アプリポータルのシステム管理者だけがユーザーの権限を設定・変更できます。

1. アプリポータルにログイン

アプリポータルにアクセスし、画面の案内にしたがってログインしてください。

利用開始やアカウント作成など、画面の進め方が分からない場合は、アプリポータルサポートのスタートアップガイドを参照してください。

2. ユーザーを選択

ログイン後、アプリポータルのユーザー画面から、アクセストークンの取得を許可するユーザーを選択します。

3. 連携権限を設定

画面右上の「編集」ボタンを押し、「アプリ連携権限」の「事業者情報」にチェックを入れて、右上の保存ボタンを押してください。

備考

このチュートリアルでは、「事業者情報」の取得機能を利用するため、この権限を設定します。
実際にマネーフォワードクラウドのサービスと連携する場合は、連携するサービスに応じた権限を設定してください。

アクセストークンを取得するフロー

API連携機能を使うエンドユーザーの連携操作開始から、アプリに対してアクセストークンが発行されるまでの一連のフローを説明します。

1. ユーザーが認可エンドポイントにアクセス

ユーザーがブラウザからパラメーターが付いた認可エンドポイント( /authorize )にアクセスします。
パラメーターは認可エンドポイントのドキュメントをご確認ください。

重要なパラメーターを以下の表に示します。

パラメーター	説明
response_type	`code` （固定値、必須）
client_id	STEP 1で発行したClient ID（必須）
scope	実装するAPI連携機能で利用するAPIに合わせたスコープ（必須）
redirect_uri	アプリに設定したリダイレクトURI（必須）
state	CSRF対策用のランダムな文字列（任意）

備考

scope というパラメーターを用いて、この連携操作で発行されるアクセストークンの権限（どのような操作ができるか）を定義します。この権限をスコープと言います。
あるAPIを呼び出すためには、そのAPIを呼び出すためのスコープを持っている必要があります。 このパラメーターは必須です。

scope に設定する値は、マネーフォワードクラウドのAPIドキュメントに記載されています。 ご利用になるマネーフォワードクラウドのサービスやAPIによって、適切な値は異なります。
実際に開発される際は、APIドキュメントをよく確認いただき、利用されるAPIに応じた正しい値を設定してください。
複数のスコープを設定する場合は、スペースで区切ります。たとえば、mfc/.../xxx.read mfc/.../xxx.write のように設定します。

例）事業者情報の取得APIの場合、リンク先に「必要なスコープ」として記載のある mfc/admin/tenant.read です。マネーフォワードクラウド請求書のAPIの場合は mfc/invoice/data.read や mfc/invoice/data.write といったスコープがあります。

2. 認可エンドポイントアクセス後のユーザーの操作

ユーザーは画面の指示にしたがって、以下の操作を行ないます。

マネーフォワードクラウドにログイン
連携する事業者の選択
アプリの情報を確認して連携を許可

3. アプリへのリダイレクト

エンドユーザーが連携を許可すると、指定した redirect_uri にリダイレクトされます。
この際、次のようなパラメーターが付加された状態でリダイレクトされます。

パラメーター	説明
code	認可コード
iss	`https://api.biz.moneyforward.com` （固定値）
state	認可エンドポイントを呼び出した際に指定した `state` パラメーター（認可リクエスト時に `state` パラメーターを指定した場合のみ）
error	エラーが発生している場合に付与される

4. アクセストークンの発行

認可コードをパラメーターとして付与してトークンエンドポイントにアクセスします。
トークンエンドポイントのアクセスに際して、以下の検証および手順を行なってください。

error パラメーターの検証（エラーが発生している場合には付与されます）
state パラメーターとセッションに保存している state が一致することの検証（認可リクエスト時に state パラメーターを指定している場合）
認可コードを code に指定してトークンエンドポイントへリクエスト
アクセストークンとリフレッシュトークンを取得

リフレッシュトークンについて

トークンエンドポイントのレスポンスには、アクセストークンとリフレッシュトークンが含まれています。

アクセストークンの期限が切れた場合、リフレッシュトークンを使ってトークンエンドポイントから新たなトークンを発行できます。リフレッシュトークンを利用してアクセストークンを取得することで、エンドユーザーは都度認可操作が不要となります。ただし、リフレッシュトークンの期限が切れた場合は、エンドユーザーは再び認可操作をする必要があります。

注意

一度利用したリフレッシュトークンは再利用できません。アクセストークンを発行するたびに、リフレッシュトークンも合わせて再発行されます。

また、リフレッシュトークンを利用して新しいトークンを発行すると、古いアクセストークンは利用できなくなります。

各トークンの期限について

各トークンの有効期限は以下の通りです。これらの値は変更できません。

1時間より長くアクセストークンを利用したい場合は、リフレッシュトークンを利用してアクセストークンを再発行してください。詳しくは、リフレッシュトークンを利用してアクセストークンを再発行するをご覧ください。

トークン	期限
アクセストークン	1時間
リフレッシュトークン	540日

トークン運用のベストプラクティス

取得したアクセストークンは、有効期限が切れるまで保持し、繰り返し使用してください。 APIを呼び出すたびに新しいアクセストークンを発行する必要はありません。

アクセストークンが期限切れになり 401 エラーが返された場合は、リフレッシュトークンを使ってアクセストークンを更新してください。このとき発行される新しいアクセストークンとリフレッシュトークンも保存し、次回以降の利用に備えてください。

詳しい実装方法については、以下のチュートリアルをご覧ください。

注意

トークンエンドポイントにはレート制限があります。APIを呼び出すたびにアクセストークンを再発行すると、レート制限に達する可能性があります。取得したアクセストークンは有効期限が切れるまで再利用してください。

実際にアクセストークンを取得する

STEP1で登録したアプリ情報を元に、実際にアクセストークンを取得してみましょう。

1. ブラウザで認可エンドポイントにアクセス

認可エンドポイントと下記のパラメーターを組み合わせて、ブラウザからアクセスします。

備考

ブラウザからのみアクセスできます。curl等ではアクセスできません。

認可エンドポイント

https://api.biz.moneyforward.com/authorize

参考 : 認可エンドポイントのリファレンス

組み合わせるパラメーター

パラメーター	説明
response_type	`code` （固定値）
client_id	STEP1で発行したClient ID
scope	`mfc/admin/tenant.read` ※1
redirect_uri	STEP1で設定したリダイレクトURI ※2

※1 : 今回はテストとして、事業者情報の取得APIのスコープ mfc/admin/tenant.read を利用します。 実際に開発される際は、ご利用になるマネーフォワードクラウドのAPIドキュメントを確認し、利用されるAPIに応じた正しい値を設定してください。複数のスコープを設定する場合は、スペースで区切ります。たとえば、mfc/.../xxx.read mfc/.../xxx.write のように設定します。

※2 : 今回のチュートリアルでは、 http://localhost:12345/callback を使用します。

組み立てた例（実際にアクセスするURIの例）

実際にアクセスするURIは次のようになります。

https://api.biz.moneyforward.com/authorize?response_type=code&client_id=${ClientID}&scope=mfc/admin/tenant.read&redirect_uri=http://localhost:12345/callback

${ClientID} の部分は、STEP1で発行したClient IDに、${ClientID} ごと書き換えてください。

2. マネーフォワードクラウドにログイン

上記URLにアクセスするとログインが求められるので、ご自身のマネーフォワード IDでログインします。

3. 連携する事業者を選択

連携する事業者を選択します。

select tenant

4. 連携を許可

連携する事業者とアプリの詳細、利用するAPIの概要（要求する権限）が表示されます。
内容に問題がなければ、右下の「許可」を押します。

allow auth

5. リダイレクトされたURLのcodeパラメーターから認可コードを取得

連携を許可すると、STEP 1で設定したアプリのリダイレクトURIへ転送されます。
このとき、リダイレクトURIにクエリパラメーターとして、認可コード（code パラメーター）が渡されます。
アプリでは、転送されたURIから code パラメーターを取得します。

※ 本チュートリアルでは、アプリのアドレスを設定していないため、接続できない旨のエラー画面が表示されます。
そのため、アドレスバーのURLから code パラメーターの値（認可コード）を直接コピーしてください。
本来は、この処理をアプリで行う必要がありますが、今回はテストとして手動で代替しています。

confirm code param

6. 認可コードを使ってアクセストークンを取得

認可コードが無事に取得できたら、curlでトークンエンドポイントにアクセスし、アクセストークンを取得します。

備考

トークンエンドポイントはブラウザではなく、プログラム（curl等）からアクセスします。

トークンエンドポイント

https://api.biz.moneyforward.com/token

参考 : トークンエンドポイントのリファレンス

cURLの例

実際に実行するcurlは以下のような形になります。

curl --request POST "https://api.biz.moneyforward.com/token" \
-u "${ClientID}:${ClientSecret}" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=authorization_code" \
-d "code=${AuthCode}" \
-d "redirect_uri=${RedirectURI}"

備考

Windows環境でこのコマンドを実行する場合は次の2つを変更してください。

curl を curl.exe に置き換える
改行と \ を削除して1行のコマンドにする

${~} の部分は、それぞれ設定および取得した下記の値に、${~} ごと書き換えてください。

パラメーター	説明
ClientID	STEP1で発行したClient ID
ClientSecret	STEP1で発行したClient Secret
AuthCode	1つ前のステップで取得した認可コード
RedirectURI	STEP1で設定したリダイレクトURI ※1

※1 : 今回のチュートリアルでは、 http://localhost:12345/callback です。

成功時のレスポンス

成功時のレスポンスは以下です。

{
  "access_token": "xxxxxxxxxxxxxxxxxx",
  "refresh_token": "yyyyyyyyyyyyyyyy",
  "scope": "mfc/admin/tenant.read",
  "token_type": "Bearer",
  "expires_in": 3600
}

以上がアクセストークンを取得するまでの手続きです。

リフレッシュトークンを利用してアクセストークンを再発行する

アクセストークンの期限切れ等で再発行が必要になった場合は、リフレッシュトークンを利用して再発行します。
※ リフレッシュトークンはアクセストークン取得時のレスポンスに含まれています。

トークンエンドポイント

https://api.biz.moneyforward.com/token

アクセストークン取得時と同じエンドポイントです。
参考 : トークンエンドポイントのリファレンス

cURLの例

curlでのリフレッシュトークンを使ったリクエスト例は以下です。

curl --request POST "https://api.biz.moneyforward.com/token" \
-u "${ClientID}:${ClientSecret}" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=refresh_token" \
-d "refresh_token=${RefreshToken}"

備考

Windows環境でこのコマンドを実行する場合は次の2つを変更してください。

curl を curl.exe に置き換える
改行と \ を削除して1行のコマンドにする

${~} の部分は、それぞれ設定および取得した下記の値に、${~} ごと書き換えてください。

パラメーター	説明
ClientID	STEP1で発行したClient ID
ClientSecret	STEP1で発行したClient Secret
RefreshToken	1つ前のステップで発行されたrefresh_token

成功時のレスポンス

成功時のレスポンスは以下です。
アクセストークンとリフレッシュトークンが新たに発行されます。

{
  "access_token": "xxxxxxxxxxxxxxxxxx",
  "refresh_token": "yyyyyyyyyyyyyyyy",
  "scope": "mfc/admin/tenant.read",
  "token_type": "Bearer",
  "expires_in": 3600
}

ユーザーへ連携権限の付与​

1. アプリポータルにログイン​

2. ユーザーを選択​

3. 連携権限を設定​

アクセストークンを取得するフロー​

1. ユーザーが認可エンドポイントにアクセス​

2. 認可エンドポイントアクセス後のユーザーの操作​

3. アプリへのリダイレクト​

4. アクセストークンの発行​

リフレッシュトークンについて​

各トークンの期限について​

トークン運用のベストプラクティス​

実際にアクセストークンを取得する​

1. ブラウザで認可エンドポイントにアクセス​

認可エンドポイント​

組み合わせるパラメーター​

組み立てた例（実際にアクセスするURIの例）​

2. マネーフォワード クラウドにログイン​

3. 連携する事業者を選択​

4. 連携を許可​

5. リダイレクトされたURLのcodeパラメーターから認可コードを取得​

6. 認可コードを使ってアクセストークンを取得​

トークンエンドポイント​

cURLの例​

成功時のレスポンス​

リフレッシュトークンを利用してアクセストークンを再発行する​

トークンエンドポイント​

cURLの例​

成功時のレスポンス​

ユーザーへ連携権限の付与

1. アプリポータルにログイン

2. ユーザーを選択

3. 連携権限を設定

アクセストークンを取得するフロー

1. ユーザーが認可エンドポイントにアクセス

2. 認可エンドポイントアクセス後のユーザーの操作

3. アプリへのリダイレクト

4. アクセストークンの発行

リフレッシュトークンについて

各トークンの期限について

トークン運用のベストプラクティス

実際にアクセストークンを取得する

1. ブラウザで認可エンドポイントにアクセス

認可エンドポイント

組み合わせるパラメーター

組み立てた例（実際にアクセスするURIの例）

2. マネーフォワードクラウドにログイン

3. 連携する事業者を選択

4. 連携を許可

5. リダイレクトされたURLのcodeパラメーターから認可コードを取得

6. 認可コードを使ってアクセストークンを取得

トークンエンドポイント

cURLの例

成功時のレスポンス

リフレッシュトークンを利用してアクセストークンを再発行する

トークンエンドポイント

cURLの例

成功時のレスポンス