APIキー交換エンドポイント
POST/auth/exchange
APIキーをJWTに交換します。
このエンドポイントは、サーバー間通信や自動化スクリプトでマネーフォワード クラウドのAPIにアクセスする際に使用します。 アプリポータルで発行したAPIキーを使用して、短期間有効なJWTを取得できます。
APIキーの形式
APIキーは以下の形式で発行されます:
mf_api_prd_{ランダム文字列}
例:
mf_api_prd_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6
認証方法
APIキーは Authorization ヘッダーに Bearer スキームで指定します:
Authorization: Bearer mf_api_prd_xxxxxxxxxxxxxxxx
JWTの特性
- 有効期限: 1時間（3600秒）
- 署名アルゴリズム: ES256（ECDSA with P-256 and SHA-256）
- スコープ: APIキー発行時に設定したサービスのスコープが含まれます
レート制限
このエンドポイントには APIキーごとに1分あたり100リクエスト の制限があります。 通常の運用では、取得したJWTを1時間キャッシュして使用するため、この制限に達することはほとんどありません。
重要: このレート制限は /auth/exchange エンドポイントにのみ適用されます。
取得したJWTを使用した各APIエンドポイントへの呼び出しには、それぞれ独自のレート制限があります。
セキュリティに関する注意事項
- APIキーは機密情報です。安全に保管し、コードに直接記述しないでください
- 環境変数やシークレット管理サービスを使用して管理してください
- 通信は必ずHTTPS経由で行ってください
詳細な使用方法については、APIキーによる認証のチュートリアルを参照してください。
レスポンス
- 200
- 401
- 429
- 500
- 503
APIキーの交換に成功したレスポンスです。
取得したJWTは1時間有効です。 トークンをキャッシュして使用し、有効期限が切れる前に再度このエンドポイントを呼び出して新しいトークンを取得してください。
APIキーが無効または期限切れのエラーです。
このエラーが発生した場合は、以下を確認してください:
- APIキーが正しいか
- APIキーが無効化されていないか
- APIキーの形式が正しいか（
mf_api_prd_で始まる）
問題が解決しない場合は、アプリポータルで新しいAPIキーを発行してください。
一定時間内のリクエスト数が制限を超過したエラーです。
Retry-Afterヘッダーで返す時間（秒）を待ってからアクセスしてください。
レスポンスヘッダー
リクエスト回数制限を超えた場合のリトライまでの時間（秒）
マネーフォワード クラウドのシステム内で予期しない問題が発生したエラーです。
サーバーメンテナンスなど一時的にサービスを利用できないエラーです。
しばらく待ってからアクセスしてください。