存取權杖的取得與更新

存取權杖刷新權杖 OAuth 有效期限

本文的對象
適用於處理呼叫 ReceiptRoller API 用的存取權杖的開發者。

將以 OAuth 授權碼流程取得的存取權杖附在 Authorization: Bearer ... 標頭呼叫 API。存取權杖有有效期限，在過期前以刷新權杖更新。

有效期限的參考

權杖	有效期限	用途
存取權杖	1 小時	API 呼叫
刷新權杖	90 天	存取權杖的更新
授權碼	10 分（一次性）	權杖初次取得

取得（授權碼 → 權杖）

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 個 worker，或使用分散鎖防止二次更新。

失效的情況

刷新權杖的 90 天有效期限已過
使用者解除了串接
密鑰被重新產生
應用程式被管理者停止
長期間（30 天以上）沒有 API 存取的情況

失效時會回傳 invalid_grant 錯誤。應用程式請導引至重新授權流程。

保管

權杖僅在伺服器端保管。避免前端、行動應用程式的本地儲存
保存於 DB 時加密（AES-256 等）
以使用者為單位保管，不與其他使用者的權杖混在一起
不輸出至日誌