freee・マネーフォワードの API トークンを、AI 記帳でどう守るか

AI に記帳をやらせるなら、どこかで必ず freee や マネーフォワード の OAuth トークンが要ります。明細を読む、仕訳を書き戻す——その入り口の鍵がトークンです。問題は、この鍵をどこに置き、どう更新し、誰が触れる状態にするか。記帳の自動化でいちばん地味に、いちばん事故が起きやすいのが、このトークンの運用です。トークンに限らず「AI に渡す情報をどこで絞るか」の全体像は、こちらの記事にまとめています。

トークンは「短命だが、広い」

freee の OAuth トークンは、アクセストークンの有効期限が6時間、リフレッシュトークンが90日です。リフレッシュトークンはローテーション方式で、更新のたびに新しいものが発行され、古いものは無効になります。「6時間で切れるなら安全」と思いたくなりますが、そこは本質ではありません。リフレッシュで回り続けますし、何より1本のトークンが、その権限の範囲の会計データへ広くアクセスできます。守るべきは「期限」ではなく、「範囲」と「置き場所」です。

いちばん危ないのは「トークンの散らばり」

顧問先や事業所が増えれば、その数だけ認可とトークンが増えます。これが各担当の PC、チャットの履歴、スクリプトの中、.env ファイルに散らばると、その一つひとつが漏洩点になります。とくに AI に読ませるディレクトリの中にトークンを置けば、何かの拍子に AI のコンテキストにも載り得ます。鍵の本数が増えるほど、置き場所の管理が破綻していく——これがトークン運用の現実です。

だから「サーバー側で一元管理」

素直な対策は、トークンをファイルではなくサーバー側で保管し、リフレッシュもアプリが自動で回すことです。画面にも、担当者の手元にも、トークンの実体を出さない。そして AI には渡さない。AI がやるのは判定で、会計サービスへの読み書きは、トークンを抱えたサーバー側が代行する。こうすると、漏洩点は「散らばった鍵」から「一元管理された一か所」に縮みます。

リフレッシュの落とし穴

90日でローテーションするということは、更新のたびに発行される新しいリフレッシュトークンを確実に保存し続けないと、いずれ認可からやり直しになります。これを顧問先ごとに、担当者が手で管理するのは現実的ではありません。トークンのライフサイクル——取得・保管・自動更新・失効時の再認可——を仕組みとして持っておくことが、結局いちばん安全で、いちばん手間が少なくなります。

実際にやったこと

私たちが社内で記帳の自動化を整えたときも、最初に決めたのはトークンの置き場所でした。トークンはファイルに一切置かず、サーバー側で保管・自動更新する。AI には渡さず、判定だけをさせる。これだけで、「どのファイルに鍵があったか」を心配する必要がなくなりました。RuleHub でも同じ設計を採っていて、freee / MoneyForward のトークンはサーバー側で保管・自動リフレッシュし、画面にも手作業にも露出させません。AI 判定はサーバー内で完結し、確定した結果だけを会計サービスへ戻します。

この設計を実運用しているのが、田村直大公認会計士・税理士事務所です。freee のトークンや口座番号はサーバー側に保管したまま、AIに渡すのは正規化済みの摘要だけ。鍵を一か所に集めて自動で回す形のまま、記帳の自動化を段階的に最大95%まで進めています（導入インタビュー）。

freee・マネーフォワード APIトークンの安全な管理：実装パターンと具体手順

freee APIまたはマネーフォワード クラウドAPIのOAuthトークンを「AI記帳」などの自動化で扱う際、具体的にどう管理するかを実装レベルで整理します。

freee API OAuthトークンの基本仕様（2026年）

• アクセストークン有効期間：24時間（リフレッシュトークンで再取得）
• リフレッシュトークン有効期間：無期限（ただし不使用期間が長すぎると失効）
• スコープ：read / write / company など細かく指定可能 → 必要最小権限のみ付与が鉄則
• 認証エンドポイント：https://accounts.secure.freee.co.jp/oauth/token

マネーフォワード クラウド APIトークンの基本仕様（2026年）

• アクセストークン有効期間：約1時間（短い！自動リフレッシュが前提）
• OAuthフロー：Authorization Code Flow（ユーザー認証が必要）
• スコープ例：invoice:read / journal:write など機能別に分離
• 認証エンドポイント：https://auth.moneyforward.com/oauth/token

サーバー側一元管理の実装パターン（推奨）

「どのアプリがどのトークンを持っているか分からない」という「トークンの散らばり」を防ぐには、トークン管理を一つのサービスに集約するアーキテクチャが最も安全です。

最小構成（シンプルなバックエンドサービス）

1. シークレットストアにトークンを格納：AWS Secrets Manager・Azure Key Vault・HashiCorp Vaultなどを使用。環境変数や設定ファイルへの直接保存は禁止
2. アクセストークンの自動リフレッシュレイヤー：freee（24時間）やMF（1時間）の有効期限前に自動でリフレッシュするバックグラウンドジョブを実装
3. APIゲートウェイパターン：フロントエンドやAIエージェントにトークンを渡さない。すべてのAPI呼び出しはバックエンドを経由させ、バックエンドがトークンを保持する

リフレッシュトークンの落とし穴と対処

マネーフォワード APIのアクセストークンは1時間で失効します。自動化処理で最も多いエラーは「アクセストークン有効期限切れ」です。対処：

1. リフレッシュ処理をミドルウェア化：APIリクエスト前にトークンの有効期限を確認し、期限まで5分以内であれば事前リフレッシュ
2. 401エラー時の自動リトライ：401 Unauthorizedが返ったら自動でリフレッシュ→リトライするリトライロジックを実装
3. リフレッシュトークン失効時のアラート：リフレッシュトークンも失効（freeeの場合は長期不使用で失効）した場合は、担当者に通知して手動再認証を促す仕組みが必要

AI記帳・自動仕訳でのトークン利用：最小権限の設計

AIが請求書を読み取って仕訳をfreee/MFに書き込む用途では、以下のスコープ設計が推奨です。

AIに渡すのは「読み取り」スコープのみで、「書き込み」は人間の確認後に別プロセスで実行するアーキテクチャが最も安全です。

RuleHub との連携：AI記帳のトークン管理を組織ポリシーで制御する

複数の担当者・顧問先でfreee/MF APIトークンを扱う場合、AurantのRuleHubを使用することで、APIアクセスのポリシーを中央集権管理できます。RuleHubはMCPプロトコルを通じて会計AIとfreee/MFを安全に橋渡しし、トークンを直接AIに渡さないアーキテクチャをサポートしています。

運用前のチェック

• トークンをファイル（.env 等）に置かず、サーバー側で保管しているか
• リフレッシュ（90日ローテーション）を自動で回す仕組みがあるか
• トークンを AI に渡していないか（AI は判定だけにできているか）
• 顧問先・事業所ごとにトークンを分離・管理できているか
• 画面や担当者の手元に、トークンの実体が出ていないか

トークンは、記帳自動化のいちばん奥にある鍵です。短命さに安心せず、置き場所と更新と権限の範囲を先に設計しておく。鍵をひとところに集めて自動で回す形にできれば、AI の速さは、認証情報の不安と切り離せます。