アクセストークンの取得と更新

アクセストークンリフレッシュトークン OAuth 有効期限

レシートローラー API は、OAuth の認可コードフローで取得したアクセストークンを Authorization: Bearer … ヘッダーに付けて呼び出します。アクセストークンは8時間で切れるので、リフレッシュトークンで更新します。この記事では、有効期限、取得と更新のリクエスト、更新のたびにリフレッシュトークンが入れ替わる仕組み、トークンが使えなくなるケースを説明します。認可URLや同意画面についてはAPI認証ガイドをご覧ください。

有効期限

トークン	有効期限	用途
アクセストークン	8時間（`expires_in: 28800`）	API の呼び出し
リフレッシュトークン	発行から30日	アクセストークンの更新（1回だけ使えます）
認可コード	10分（1回だけ使えます）	最初のトークン取得

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

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

grant_type=authorization_code
&code=AUTHORIZATION_CODE
&redirect_uri=https%3A%2F%2Fexample.com%2Fcallback
&client_id=YOUR_CLIENT_ID
&client_secret=YOUR_CLIENT_SECRET

PKCE を使った場合は code_verifier も送ります。公開クライアントは client_secret を送らず、code_verifier が必須です。

レスポンス

{
  "access_token": "…",
  "refresh_token": "…",
  "token_type": "Bearer",
  "expires_in": 28800,
  "scope": "store.products.read store.orders.read",
  "accessToken": "…",
  "refreshToken": "…",
  "tokenType": "Bearer",
  "expiresIn": 28800
}

camelCase のキーは古いクライアント向けに同じ値を重ねて返しているものです。新しく作るアプリは snake_case のキーを読んでください。

更新する（リフレッシュトークン → 新しいトークン）

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

grant_type=refresh_token
&refresh_token=REFRESH_TOKEN
&client_id=YOUR_CLIENT_ID
&client_secret=YOUR_CLIENT_SECRET

レスポンスの形は取得時と同じです。公開クライアントは client_secret を送りません。

更新するたびに、新しいアクセストークンと新しいリフレッシュトークンが返ります。毎回両方を保存し直してください。
更新に使ったリフレッシュトークンと、それと組の古いアクセストークンは、その時点で無効になります。古いアクセストークンの期限が残っていても使えません。
新しいリフレッシュトークンの有効期限は、更新した時点から30日です。30日以内に一度でも更新すれば、再認可なしで使い続けられます。
スコープと紐付くビジネスアカウントは、更新前のトークンと同じです。

更新のタイミング

期限前に更新: expires_in から期限を計算し、切れる少し前に更新します。
401 を受けたら更新: API が 401 を返したら一度だけ更新して再試行し、それでも 401 なら再認可へ進みます。

同じリフレッシュトークンで2回更新すると、2回目は invalid_grant になります。複数のプロセスが同じトークンを使うシステムでは、更新を1か所にまとめるか、ロックで同時に更新しないようにしてください。

トークンが使えなくなるケース

ケース	起きること
リフレッシュトークンの30日が過ぎた	更新が 401 `invalid_grant`。再認可が必要です。
使用済みのリフレッシュトークンで更新した	401 `invalid_grant`。最後に受け取ったリフレッシュトークンを使ってください。
ビジネスアカウントのオーナーが「連携アプリ」で連携を取り消した	そのビジネスアカウントに対するアプリのトークンがすべて無効になり、API は 401、更新は `invalid_grant` になります。
アプリが `/api/v1/auth/revoke` で取り消した	そのアクセストークンとリフレッシュトークンの組が無効になります。
クライアントシークレットを再生成した	発行済みのアクセストークンは期限まで使えますが、古いシークレットでの更新は 401 `invalid_client` になります。新しいシークレットに入れ替えてください。
アプリを削除した	アプリのトークンもすべて削除されます。更新は 401 `invalid_client` です。
ビジネスアカウントのプランがスタータープラン未満になった	更新が 401 `invalid_grant`（`error_description` にプランが必要な旨）。トークンは取り消されないため、プランを戻せば同じリフレッシュトークンで更新できます。

再認可が必要なときは、ユーザーを認可URLへもう一度案内してください。

トークンの状態を確かめる

POST https://receiptroller.io/api/v1/auth/verify
Content-Type: application/json

{ "accessToken": "ACCESS_TOKEN" }

有効なら 200 で active、clientId、scope、expiresAt、organizationId が返り、無効なら 401 です。organizationId はトークンが紐付くビジネスアカウントで、紐付かないトークンでは null です。

保管

トークンはサーバー側で保管し、ブラウザのローカルストレージには置かないでください。モバイルアプリでは端末の安全な保存領域（iOS のキーチェーンなど）を使ってください。
データベースに保存する場合は暗号化してください。
ユーザーやビジネスアカウントごとに分けて保管し、取り違えないようにしてください。
ログに出力しないでください。