delegateAccessTokenCreate が expiresIn を返すようになった

図解 ： delegateAccessTokenCreate が expiresIn を返すようになった Admin GraphQL API / 2026-04 delegateAccessTokenCreate が expiresIn を返すようになった 委任トークン（delegate token）を作る際、レスポンスに「あと何秒で失効するか」が含まれるように。特に有効期限を指定せず親トークンの TTL を継承させたときの、これまで知る術がなかった失効時刻が判明する。 このページの構成 何が変わったのか（30秒で理解） 仕組み図解 ： mutation がトークンと一緒に返すもの 特に効くケース ： expiresIn 未指定 ＝ 親 TTL 継承 従来 vs 今回 の比較 利用条件 技術者が押さえるべき5つのポイント 業務に活かせる3つのユースケース 提案で使える1行サマリ 1 何が変わったのか delegateAccessTokenCreate mutation が返す DelegateAccessToken 型に expiresIn フィールドが追加 された。 値は 「失効までの残り秒数」 。これにより、委任トークンを使うアプリ開発者が トークンがいつ失効するかを正確に把握 できるようになった。 従来 ： 失効時刻が読めない トークンは作れるが、レスポンスに有効期限の情報が無い。特に有効期限を指定しなかった場合、いつ切れるか把握する手段が無かった。 今回 ： 残り秒数が返る レスポンスの expiresIn に「あと何秒で失効するか」が入る。これで更新タイミングの設計や監視が可能に。 2 仕組み図解 ： mutation がトークンと一緒に返すもの # mutation のレスポンス例（イメージ） { "delegateAccessToken" : { "accessToken" : "shpat_xxxxxxxx" , "expiresIn" : 86399 // 失効までの残り秒数 } } 委任トークン（delegate token）とは ： アプリが自分の親トークンから、権限の一部を切り出して発行する子トークン。 expiresIn 入力で TTL（有効期間）を指定できる。 今回追加されたのはレスポンス側の expiresIn で、これは「失効までの残り秒数」を表す。 （上記コードのフィールド以外の具体的なスキーマ詳細は記事に記載なし） 3 特に効くケース ： expiresIn 未指定 ＝ 親 TTL 継承 記事が「特に有益（particularly beneficial）」と名指ししているのが、 入力の expiresIn を指定しなかった ケース。このとき委任トークンは 親トークンの TTL（Time to Live）を継承 する。 親 TTL 継承トークンは「入力値から逆算」ができないため、失効時刻を知る手段が従来は存在しなかった。 レスポンスの expiresIn がその空白を埋める のが、この更新の核心。 4 従来 vs 今回 の比較 項目 従来 今回（2026-04〜） expiresIn 指定時の失効把握 手計算 入力値から自分で推定 確定 レスポンスの値で把握 expiresIn 省略時（親 TTL 継承） 不可 失効時刻を知る術が無い 判明 残り秒数が返る REST delegate endpoint との整合 REST 側にのみ有効期限データあり 整合 GraphQL でも同等のデータ 値の形式 — 失効までの 残り秒数 （seconds remaining） 対象 API バージョン — 2026-04 以降 5 利用条件 GraphQL Admin API 2026-04 以降 この expiresIn フィールドは GraphQL Admin API version 2026-04 以降 で利用可能。古いバージョンを呼んでいるアプリは API バージョンの更新が必要。 delegateAccessTokenCreate を使う構成 委任トークンを発行するアプリが対象。発行時のレスポンスに新フィールドが含まれる。 対象プラン等の追加条件は記事に記載なし。 記事に記載があるのは「2026-04 以降」「残り秒数を返す」「REST delegate endpoint と整合」「未指定時に有益」の 4 点まで。フィールドの厳密な型・nullability・既存トークンへの遡及可否などは記事に記載なし。導入前に該当バージョンのスキーマで実値を確認すること。 6 技術者が押さえるべき5つのポイント 1. 値は「絶対時刻」でなく「残り秒数」 expiresIn は失効までの秒数。失効時刻として保持したいなら、 取得時刻 + expiresIn で自分でタイムスタンプ化する。タイムゾーン非依存で扱える反面、受信時刻の基準を決めておく必要がある。 2. 未指定時の親 TTL 継承が主役 入力 expiresIn を省くと子は親 TTL を継承する。 この場合の失効把握が今回の最大の利得 。明示指定運用なら恩恵は限定的だが、継承運用なら更新ロジックを組み直せる。 3. REST delegate endpoint と同等データ REST Admin API の delegate エンドポイントで取れていた有効期限データと整合する。 REST → GraphQL 移行時に、失効情報の欠落という非互換が解消 される。 4. プロアクティブな更新が組める 失効を「使ってから 401 で気づく」のではなく、 残り秒数を見て事前にリフレッシュ する設計が可能に。トークン失効起因の断続的な失敗を予防できる。 5. 取得にはバージョン更新が前提 expiresIn は 2026-04 以降のバージョン でないと返らない。古い API バージョン固定のアプリは、まず呼び出しバージョンを上げる必要がある。 クエリに expiresIn を追記しただけでは旧バージョンでは効かない 点に注意。既存トークンへの遡及や他フィールド仕様は記事に記載が無いため、実スキーマで検証すること。 7 業務に活かせる3つのユースケース USE CASE 1 委任トークンのプロアクティブ更新で「失効起因の障害」をゼロに 課題 委任トークンを外部サービスやバックエンドに渡して運用しているが、失効タイミングが読めず、切れた瞬間に 401 で処理が落ちる事故が散発。 打ち手 発行レスポンスの expiresIn を保存し、残り秒数が閾値を切る前にトークンを再発行するジョブを組む。 効果 「使って初めて失効に気づく」運用から「期限前に先回りして更新」へ移行。間欠的な決済・同期失敗を予防。 技術メモ 受信時刻＋ expiresIn で失効時刻を算出してキャッシュ。残り秒数を直接保持すると経過で陳腐化するため、絶対時刻に正規化して持つ。 USE CASE 2 REST delegate endpoint から GraphQL への移行をデータ欠落なしで完遂 課題 REST の delegate エンドポイント前提で書かれた既存処理を GraphQL Admin API へ寄せたいが、移行すると有効期限データが取れなくなる非互換が懸念だった。 打ち手 2026-04 以降に上げて delegateAccessTokenCreate を使い、レスポンスの expiresIn で REST と同等の失効情報を取得。 効果 失効情報を落とさず GraphQL に一本化。REST 依存を減らし、API の将来性に寄せられる。 技術メモ REST 側の期限表現とフィールド意味（残り秒数）を突き合わせ、移行前後で同じ失効ロジックが再現できるかを回帰テストで担保。 USE CASE 3 親 TTL 継承トークンの寿命を可視化し、監視・アラートに載せる 課題 有効期限を明示せず親 TTL 継承で委任トークンを発行している箇所が複数あり、どれがいつ切れるか把握できず運用がブラックボックス化。 打ち手 発行時に返る expiresIn をログ・メトリクスに記録し、残り秒数が短いトークンをダッシュボード／アラートで可視化。 効果 これまで知る術が無かった継承トークンの寿命が見えるようになり、失効前の更新・棚卸しが回せる。 技術メモ 継承運用は入力値から逆算できないため、レスポンス値が唯一の根拠。発行ごとに失効時刻を残し、監視側で残時間を再計算する。 8 提案で使える1行サマリ 「 delegateAccessTokenCreate のレスポンスに 失効までの残り秒数 expiresIn が追加（2026-04 以降）。 特に有効期限を指定せず親 TTL を継承させたトークンの“いつ切れるか”が初めて分かる ようになり、 プロアクティブな更新・監視・REST からの移行が組めるようになった。」 source ： shopify.dev / changelog / delegateAccessTokenCreate mutation now returns expiresIn published 2026-04-01 ／ generated 2026-05-25