OAuth認可コードフローで取得したアクセストークンを Authorization: Bearer ... ヘッダーに付けてAPIを呼び出します。アクセストークンには有効期限があり、期限切れ前にリフレッシュトークンで更新します。

有効期限の目安

取得（認可コード → トークン）

POST https://receiptroller.io/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&code={認可コード}
&redirect_uri={登録済みURI}
&client_id={クライアントID}
&client_secret={クライアントシークレット}

レスポンス

{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "rrrt_xxxxxxxxxxxx",
  "scope": "store.read receipt.read"
}

更新（リフレッシュトークン → 新アクセストークン）

POST https://receiptroller.io/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token
&refresh_token={リフレッシュトークン}
&client_id={クライアントID}
&client_secret={クライアントシークレット}

レスポンスには新しいアクセストークンと、場合によっては新しいリフレッシュトークンが含まれます。新しいリフレッシュトークンが返された場合は、必ず保存して以降そちらを使ってください（旧リフレッシュトークンは失効）。

更新タイミングの実装パターン

• 事前更新：有効期限の5分前に自動更新（推奨）
• 遅延更新：401エラーを受けてから更新して再試行
• 事前＋遅延併用：基本は事前、想定外の失効に備えて遅延も実装

多数の同時リクエストが走るシステムでは、トークン更新を1つのワーカーに集約するか、分散ロックを使って二重更新を防いでください。

失効するケース

• リフレッシュトークンの90日有効期限切れ
• ユーザーが連携を解除した
• シークレットが再生成された
• アプリが管理者によって停止された
• 長期間（30日以上）APIアクセスがなかった場合

失効時はinvalid_grant エラーが返ります。アプリは再認可フローへ誘導してください。

保管

• トークンはサーバー側のみで保管。フロントエンド・モバイルアプリのローカルストレージは避ける
• DBに保存する場合は暗号化（AES-256など）
• ユーザー単位で保管し、他ユーザーのトークンと混在させない
• ログに出力しない

関連ガイド

• API認証ガイド（OAuth 2.0 認可コードフロー）
• クライアントID・シークレットの管理
• シークレットのローテーションと安全な保管
• 開発者ヘルプトップへ戻る