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

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

note

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

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

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

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

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

caution

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

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

以下よりアプリポータルにアクセスし、画面の案内に従ってログインしてください。
▶ アプリポータル

2. ユーザーを選択

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

3. 連携権限を設定

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

info

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

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

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

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

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

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

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

info

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

scope に設定する値は、マネーフォワード クラウドのAPIドキュメントに記載されています。 ご利用になるマネーフォワード クラウドのプロダクトやAPIによって、適切な値は異なります。
実際に開発される際は、APIドキュメントをよく確認いただき、利用されるAPIに応じた正しい値を設定してください。

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

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

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

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

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

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

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

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

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

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

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

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

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

caution

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

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

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

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

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

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

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

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

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

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

info

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

認可エンドポイント

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

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

組み合わせるパラメータ

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

※1 : 今回はテストとして、事業者情報の取得APIのスコープ mfc/admin/office.read を利用します。 実際に開発される際は、ご利用になるマネーフォワード クラウドのAPIドキュメントを確認し、利用されるAPIに応じた正しい値を設定してください。
※2 : 今回のチュートリアルでは、 http://localhost:12345/callback を使用します。

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

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

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

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

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

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

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

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

4. 連携を許可

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

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

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

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

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

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

info

トークンエンドポイントはブラウザではなく、プログラム（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環境をご利用の方は curl を curl.exe へ置き換えてください。
また、 ${~} の部分は、それぞれ設定および取得した下記の値に、${~} ごと書き換えてください。

パラメータ	説明
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/office.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環境をご利用の方は curl を curl.exe へ置き換えてください。
また、 ${~} の部分は、それぞれ設定および取得した下記の値に、${~} ごと書き換えてください。

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

成功時のレスポンス

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

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