API に JWT expired と言われたとき、私はすぐ token が壊れているとは考えません。まず exp を確認し、verifier clock と比較し、本当に new token が必要なのか、別 validation error を expiration と誤認しているのかを分けます。
最初は JWT 有効期限チェック で exp / iat / nbf の UTC を見ます。
Step 1: exp を過ぎているか確認する
{
"iat": 1789200000,
"exp": 1789203600
}
NumericDate は seconds です。
const expired = Date.now() >= payload.exp * 1000;
raw number のまま考えるより readable UTC に変換して system logs と並べます。
Step 2: laptop ではなく server clock を見る
実際に reject している service の clock が基準です。
私は：
- decoded
exp - API server time
- IdP time
- configured tolerance
を比較します。
boundary の数秒差なら skew を疑いますが、45 分前に expired した token を clock skew のせいにはしません。
大きな tolerance を入れて error を隠すこともしません。
Step 3: 401 が本当に expiration を意味するか
RFC 6750 の invalid_token は expired 以外にも revoked、malformed、otherwise invalid を含みます。
401 Unauthorized
invalid_token
token expired
jwt expired
signature has expired
server logs が具体的に expiration を示し、decoded time も一致するなら diagnosis は明確です。generic なら signature / issuer / audience も確認します。
Step 4: legitimate renewal path を使う
本当に expired なら payload を編集しません。
exp を未来に書き換えると signed bytes が変わり、元 signature は invalid になります。
通常の recovery は：
- application の refresh flow で new access token を得る。
- refresh がない/invalid なら reauthenticate する。
- client が expired token を cache/reuse しているなら token lifecycle を直す。
Decoder は renewal tool ではありません。
access token と refresh token を混同しない
OAuth の場合、access token は API に送る credential、refresh token は authorization server から new access token を得るための credential です。
私は live refresh token を debugging site に貼りません。expired access token より長寿命で高価値な credential の可能性があります。
exp が未来なら別問題へ進む
active に見えるなら：
nbfは未来か。- signature は trusted key で通るか。
issは expected issuer か。audは current API 向けか。- ID token を access token と間違えていないか。
- API が max token age / revocation policy を持っていないか。
を見ます。
JWT Validator で structure/time、JWT デバッガー で issuer/audience を切り分けます。
missing exp は profile 依存
exp がないからすべての JWT が malformed とは限りません。個別 token profile が required claims を決めます。
short-lived access token で missing expiration なら強く調査しますが、別用途 JWT に universal rule を適用しません。
expired でも signature は valid になり得る
JWT は：
- Base64URL が正しい。
- JSON が正しい。
- signature が cryptographically valid。
- issuer も audience も正しい。
- しかし expired。
という状態になれます。
signature verification は integrity/authenticity、expiration は別の claim-validation rule です。JWT 署名検証 が valid で exp が過去でも矛盾ではありません。
私の expired-token recovery checklist
- JWT 有効期限チェック を開く。
expを Unix seconds として変換する。- verifier clock と比較する。
iat/nbfも見る。- server error が本当に expiration を示すか確認する。
- expired なら refresh / reauthentication で replace する。
expを編集して old signature を再利用しない。- active なら signature、issuer、audience に進む。
時刻の仕組みは JWT exp claim ガイド を、時間が正しいのに 401 が続く場合は JWT 401 ガイド を使います。
実務上のポイントは、expired JWT は well-formed で correctly signed でも、acceptance window が終わったため reject されるということです。
