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

APIキーによる認証

このドキュメントでは、 APIキーとはなにか、それを使用した認証について説明します。

APIキーとは​

APIキーは、プログラムによるマネーフォワード クラウドのAPIへのアクセスをするための認証方式です。サーバー間通信、自動化スクリプト、AI Agentなど、ユーザーの操作を必要とせずにAPIを呼び出すことができます。

APIキーは、アプリポータルで発行され、一度だけ表示されます。発行されたAPIキーは安全に保管し、コード内に直接記述せず、環境変数やシークレット管理サービスを使用して管理してください。APIキーはパスワードと同じく、誰にも共有してはいけません。

APIキーとトークンの違い: APIキーは、パスワードのような長期的な認証情報（クレデンシャル）です。APIキー自体をAPIリクエストに直接使用するのではなく、まずAPIキーを使用してJWTに交換します。このトークンは1時間有効で、実際のAPI呼び出しに使用します。この2段階のアプローチにより、セキュリティが向上し、APIキーの露出を最小限に抑えることができます。

APIエンドポイントの対応状況

各APIエンドポイントがサポートする認証方式（APIキー、OAuth、または両方）は異なります。使用予定のAPIエンドポイントがどの認証方式をサポートしているか、APIリファレンスで確認してください。

OAuth 2.0認可フローとの違い​

マネーフォワード クラウドのAPIへのアクセスには、APIキーとOAuth 2.0認可フローの2つの認証方式があります。どちらの方式を使用するかは、アプリケーションの種類や利用シーンによって異なります。

項目APIキーOAuth 2.0認可フロー
認証の対象ユーザーの権限で実行事業者全体のデータにアクセス
トークンの有効期限APIキー自体に期限なし（JWTは1時間）アクセストークンは1時間、リフレッシュトークンで更新可能
権限の範囲APIキー発行時にサービス単位で設定ユーザーの同意に基づいてスコープを指定

どちらの認証方式を選ぶべきか​

APIキーはユーザーの権限でAPIを実行する必要がある場合に使用します。

OAuth 2.0認可フローは事業者全体のデータにアクセスする必要がある場合に使用します。

OAuth 2.0認可フローの詳細は、OAuth 2.0認可フローのドキュメントを参照してください。

APIキーの仕組み​

APIキーを使用してマネーフォワード クラウドのAPIにアクセスする流れは、以下の4つのステップで構成されます:

STEP 1: APIキーの発行​

アプリポータルでAPIキーを発行します。APIキーは、アクセス対象となるサービスを指定して発行します。APIキーは一度だけ表示されるため、安全な場所に保管してください。

STEP 2: JWTの取得​

発行されたAPIキーを使用して、/auth/exchangeエンドポイントにリクエストを送信し、短期間有効なJWTを取得します。このトークンは1時間有効です。

POST https://api.biz.moneyforward.com/auth/exchange
Authorization: Bearer mf_api_prd_xxxxxxxxxxxxxxxx

レスポンス:

{
  "access_token": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600
}

STEP 3: APIの呼び出し​

取得したJWTを使用して、マネーフォワード クラウドのAPIを呼び出します。トークンはAuthorizationヘッダーにBearerスキームで指定します。

GET https://api.biz.moneyforward.com/{service}/api/v1/...
Authorization: Bearer eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9...

STEP 4: トークンの更新​

JWTは1時間で有効期限が切れます。トークンが期限切れになった場合は、再度/auth/exchangeエンドポイントを呼び出して新しいトークンを取得してください。

APIキーの形式​

APIキーは以下の形式で発行されます:

mf_api_prd_{ランダム文字列}
  • プレフィックス: mf_api_prd_ - Money ForwardのAPIキーであることを示します
  • ランダム文字列: セキュアなランダム文字列

実際の例:

mf_api_prd_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6

レート制限​

APIキーには以下のレート制限が適用されます:

/auth/exchangeエンドポイント​

/auth/exchangeエンドポイントには、APIキーごとに1分あたり100リクエストの制限があります。この制限を超えると、429 Too Many Requestsエラーが返されます。

通常の運用では、取得したJWTを1時間キャッシュして使用するため、この制限に達することはほとんどありません。

JWTを使用したAPI呼び出し​

JWTを使用した各APIエンドポイントへの呼び出しには、それぞれ独自のレート制限があります。詳細は各APIサービスのドキュメントを参照してください。

注意

/auth/exchangeのレート制限とJWTを使用したAPI呼び出しのレート制限は別々にカウントされます。

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

APIキーを安全に管理するため、以下の点に注意してください:

1. APIキーを安全に保管する​

  • コードに直接記述しない: ソースコードにAPIキーをハードコードしないでください
  • バージョン管理システムにコミットしない: .envファイルや設定ファイルは.gitignoreに追加してください
  • 環境変数を使用する: 環境変数やシークレット管理サービス（AWS Secrets Manager、HashiCorp Vaultなど）を使用してください

2. 最小権限の原則に従う​

APIキーを発行する際は、必要最小限のサービスのみを選択してください。不要なサービスへのアクセス権限は付与しないでください。

3. 定期的なローテーション​

セキュリティを強化するため、APIキーは定期的に新しいものに更新（ローテーション）することを推奨します。古いAPIキーは無効化してください。

4. APIキーの漏洩時の対応​

APIキーが漏洩した可能性がある場合は、直ちにアプリポータルで該当のAPIキーを無効化し、新しいAPIキーを発行してください。

注意

APIキーが漏洩した場合、弊社は一切の保証を提供できません。APIキーは厳重に管理し、漏洩を防ぐようお願いいたします。

漏洩に関するご相談やサポートが必要な場合は、アプリポータルサポートまでお問い合わせください。

5. 通信の暗号化​

APIキーやJWTを送信する際は、必ずHTTPS通信を使用してください。HTTPSを使用することで、通信内容が暗号化され、中間者攻撃を防ぐことができます。

6. JWTの安全な管理​

取得したJWTもAPIキーと同ように機密情報です。メモリ内で管理し、ログに出力したり、クライアントに送信したりしないでください。

次のステップ​

APIキーの概念を理解したら、実際に使用してみましょう: