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

STEP 2: APIキーをJWTに交換する

このステップでは、発行したAPIキーを使用して、JWTを取得する方法を学習します。JWTは、マネーフォワード クラウドのAPIを呼び出す際に使用する短期間有効な認証トークンです。

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

APIキーをJWTに交換するには、/auth/exchangeエンドポイントを使用します。

エンドポイント情報​

  • URL: https://api.biz.moneyforward.com/auth/exchange
  • メソッド: POST
  • 認証: APIキーをAuthorizationヘッダーにBearerスキームで指定
  • リクエストボディ: 不要

curlを使用したリクエスト例​

以下は、curlコマンドを使用してJWTを取得する例です:

curl -X POST https://api.biz.moneyforward.com/auth/exchange \
  -H "Authorization: Bearer mf_api_prd_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"
Windows環境での注意

Windowsのコマンドプロンプトを使用する場合は、行継続文字が異なります:

curl -X POST https://api.biz.moneyforward.com/auth/exchange ^
  -H "Authorization: Bearer mf_api_prd_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"

PowerShellを使用する場合は、バッククォート(`)を使用します:

curl -X POST https://api.biz.moneyforward.com/auth/exchange `
  -H "Authorization: Bearer mf_api_prd_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"

環境変数を使用した例​

APIキーを環境変数に保存している場合は、以下のように参照できます:

curl -X POST https://api.biz.moneyforward.com/auth/exchange \
  -H "Authorization: Bearer $MF_API_KEY"

レスポンス​

成功時のレスポンス (200 OK)​

リクエストが成功すると、以下の形式でJWTが返されます:

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

レスポンスフィールドの説明:

フィールド型説明
access_tokenstringJWT。マネーフォワード クラウドのAPIを呼び出す際に使用します。
token_typestringトークンのタイプ。常に"Bearer"です。
expires_innumberトークンの有効期限（秒単位）。常に3600（1時間）です。

エラーレスポンス​

401 Unauthorized - APIキーが無効​

APIキーが無効、または期限切れの場合:

{
  "errors": [
    {
      "code": "INVALID_API_KEY",
      "message": "The provided API key is invalid or has been revoked."
    }
  ]
}

原因:

  • APIキーが間違っている
  • APIキーが無効化されている
  • APIキーの形式が正しくない

対処方法:

  • APIキーを再確認してください
  • 必要に応じて、新しいAPIキーを発行してください

429 Too Many Requests - レート制限超過​

リクエスト数が制限を超えた場合:

{
  "errors": [
    {
      "code": "RATE_LIMIT_EXCEEDED",
      "message": "Rate limit exceeded."
    }
  ]
}

原因:

  • 1分間に100リクエストの制限を超えた

対処方法:

  • 取得したJWTを1時間キャッシュして使用してください
  • トークンの取得頻度を減らしてください
レート制限の適用範囲

100リクエスト/分のレート制限は、/auth/exchangeエンドポイントにのみ適用されます。取得したJWTを使用した各APIエンドポイントへの呼び出しには、それぞれ独自のレート制限があります。

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

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

取得したJWTを使用して、マネーフォワード クラウドのAPIを呼び出すことができます。

基本的な使用方法​

JWTは、AuthorizationヘッダーにBearerスキームで指定します:

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

curlを使用した例​

# JWTを変数に保存
ACCESS_TOKEN="eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9..."

# APIを呼び出す（サービスとエンドポイントは例です）
curl -X GET https://api.biz.moneyforward.com/{service}/api/v1/... \
  -H "Authorization: Bearer $ACCESS_TOKEN"
API呼び出しの詳細

具体的なAPIエンドポイントの使用方法については、各サービスのAPIリファレンスを参照してください。

実装例: Node.jsでのトークン取得​

以下は、Node.jsを使用してJWTを取得する実装例です:

const fetch = require('node-fetch');

// 環境変数からAPIキーを取得
const apiKey = process.env.MF_API_KEY;

if (!apiKey) {
  throw new Error("MF_API_KEY environment variable is not set");
}

// /auth/exchangeエンドポイントにリクエスト
fetch('https://api.biz.moneyforward.com/auth/exchange', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${apiKey}`
  }
})
  .then(response => {
    // レスポンスの確認
    if (response.status === 200) {
      return response.json();
    } else if (response.status === 401) {
      throw new Error("Error: Invalid API key");
    } else if (response.status === 429) {
      throw new Error("Error: Rate limit exceeded. Please try again later.");
    } else {
      return response.text().then(text => {
        throw new Error(`Error: ${response.status} - ${text}`);
      });
    }
  })
  .then(tokenData => {
    const accessToken = tokenData.access_token;
    const expiresIn = tokenData.expires_in;

    console.log("Access token obtained successfully");
    console.log(`Token expires in ${expiresIn} seconds`);

    // 取得したトークンを使用してAPIを呼び出す
    // fetch('https://api.biz.moneyforward.com/{service}/api/v1/...', {
    //   headers: {
    //     'Authorization': `Bearer ${accessToken}`
    //   }
    // })
  })
  .catch(error => {
    console.error(error.message);
  });

エラーハンドリング​

実装時は、適切なエラーハンドリングを行ってください:

const fetch = require('node-fetch');

/**
 * APIキーをJWTに交換する
 *
 * @param {string} apiKey - Money Forward APIキー
 * @returns {Promise<Object>} トークン情報 {access_token: string, expires_in: number}
 * @throws {Error} APIキーが無効な場合またはその他のエラーが発生した場合
 */
async function exchangeApiKeyForJwt(apiKey) {
  try {
    const response = await fetch('https://api.biz.moneyforward.com/auth/exchange', {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${apiKey}`
      },
      timeout: 10000  // タイムアウトを設定（ミリ秒）
    });

    if (response.status === 200) {
      return await response.json();
    } else if (response.status === 401) {
      throw new Error("Invalid API key");
    } else if (response.status === 429) {
      throw new Error("Rate limit exceeded. Please try again later.");
    } else {
      const text = await response.text();
      throw new Error(`Unexpected error: ${response.status} - ${text}`);
    }
  } catch (error) {
    if (error.message.includes('fetch')) {
      throw new Error(`Network error: ${error.message}`);
    }
    throw error;
  }
}

まとめ​

このステップでは、以下のことを学習しました:

  • /auth/exchangeエンドポイントを使用してJWTを取得する方法
  • レスポンスの構造とJWTの内容
  • エラーレスポンスの種類と対処方法
  • JWTを使用したAPI呼び出しの基本
  • Node.jsでの実装例

次のステップ​

JWTの取得方法を理解したら、次は実装のベストプラクティスを学習しましょう。

トークンのキャッシュ、更新タイミング、エラーハンドリングなどの実装パターンを学習します:

STEP 3: 実装のベストプラクティス →