appDowngradeAccessScopes アプリの権限を「write → read」に格下げできるようになった

図解 ： appDowngradeAccessScopes ― アプリのアクセススコープを write から read に格下げ Admin GraphQL API 2027-01 / 新 mutation appDowngradeAccessScopes アプリの権限を「write → read」に格下げできるようになった Shopify-managed installation を使うアプリが、任意の書き込みスコープを対応する読み取りスコープに置き換えられる。読み取り権限を失わずに書き込み権限だけを手放せる。既存アプリの対応は不要。 このページの構成 そもそも何が変わるのか（30秒で理解） 仕組み図解 ： Revoke と Downgrade の違い バリデーションのルール Revoke vs Downgrade の比較 対象になるアプリ 使い方（3ステップ＋コード例） 技術者が押さえるべき5つのポイント 業務に活かせる3つのユースケース 提案で使える1行サマリ 1 そもそも何が変わるのか Admin GraphQL API 2027-01 から、新しい mutation appDowngradeAccessScopes が使えるようになる。 アプリが 任意（optional）の write スコープを、対応する read スコープに置き換える ためのもの。既存アプリの対応は不要。 これまで ： Revoke しかない appRevokeAccessScopes で write スコープを取り消すと、その write 経由でしか付与されていなかった read アクセスも一緒に消える。 これから ： Downgrade を選べる appDowngradeAccessScopes なら write だけを手放し、対応する read は残る。例 ： write_products → read_products 。 2 仕組み図解 ： Revoke と Downgrade の違い 使い分けの原則 ： read アクセスが write スコープ経由でしか付与されていない場合、Revoke すると read も消える。 アプリがまだ read を必要とするなら Downgrade を使う 、と記事は明示している。 3 バリデーションのルール optional_scopes に宣言済み 対象は任意スコープのみ 対応する read がある write write → 同名の read へ 必須スコープは不可 required は downgrade できない 未付与の write は無視 エラーにはならず素通り オール・オア・ナッシング ： リクエストしたスコープのうち 1 つでもバリデーションに失敗するとリクエスト全体が拒否 され、インストールのスコープは一切変わらない。影響範囲は 呼び出したアプリ自身のインストールのみ 。 4 Revoke vs Downgrade の比較 項目 appRevokeAccessScopes appDowngradeAccessScopes write スコープ 削除 削除 write 経由でのみ付与された read 一緒に消える 対応する read に置換して残る 向いている場面 そのリソースへのアクセス自体が不要になった 書き込みは不要だが、読み取りはまだ必要 利用可能バージョン 記載なし 2027-01〜 Admin GraphQL API 5 対象になるアプリ Shopify-managed installation を使っている インストールとスコープ管理を Shopify に任せる方式のアプリが対象。 optional write スコープ＋対応 read を宣言している 任意の write スコープと、それに対応する read スコープを持っていること。 既存アプリは対応不要。 使いたいアプリだけが API 2027-01 以降で呼び出せばよい追加機能。 6 使い方（3ステップ＋コード例） 1 不要になった write を特定 作成・更新が不要になった optional write スコープを洗い出す。 2 mutation を呼ぶ API 2027-01 以降で appDowngradeAccessScopes に対象スコープを渡す。 3 結果を確認 downgraded で成功したスコープを、 userErrors で失敗理由を確認。 mutation { appDowngradeAccessScopes (scopes: [ "write_products" ]) { downgraded { handle } userErrors { field message } } } downgraded 格下げに成功した write スコープ 正常に変更された write スコープの handle が返る。 userErrors バリデーション失敗 field と message で失敗内容を確認する。1 件でも失敗すれば全体が拒否される点に注意。 7 技術者が押さえるべき5つのポイント 1. API 2027-01 からのみ利用可能 それより前のバージョンでは呼べない。使うなら API バージョンの引き上げが前提。 2. 対象は optional_scopes のみ required スコープは downgrade できない。格下げの可能性がある write は、最初から optional_scopes 側に置く設計が必要。 3. バリデーションはアトミック 1 件でも不正があると全体が拒否され、スコープは変わらない。複数を一度に渡すときは userErrors のハンドリングが必須。 4. 未付与の write は無視される 現在付与されていない write はエラーにならず無視される。実際に変わったものは downgraded で判定する。 5. Revoke と Downgrade を取り違えない appRevokeAccessScopes で write を取り消すと、write 経由でしか付与されていなかった read も消える。 read をまだ使うコード（同期処理・表示など）が残っているなら Downgrade を選ぶ 。影響は呼び出したアプリ自身のインストールにのみ及ぶ。 8 業務に活かせる3つのユースケース USE CASE 1 最小権限への見直し（使わなくなった書き込み権限の返上） 課題 以前は商品の作成・更新機能があったが廃止した。 write_products を持ち続けているが、商品データの読み取りはまだ使っている。 打ち手 appDowngradeAccessScopes(scopes: ["write_products"]) を呼び、 read_products に格下げする。 効果 読み取りベースの機能を止めずに、不要な書き込み権限だけを手放せる。 技術メモ write_products が optional_scopes に宣言されていることが前提。required なら格下げ不可。 USE CASE 2 機能の段階的な縮退を「読み取り専用モード」として実装 課題 アプリ内の編集機能を止めて閲覧のみにしたい。Revoke を使うと read アクセスまで消え、閲覧機能も壊れてしまう。 打ち手 編集機能を止めるタイミングで、該当する optional write スコープを Downgrade する。 効果 閲覧機能を維持したまま、権限の実態をアプリの機能に合わせられる。 技術メモ Revoke との違い（read が残るかどうか）を設計段階で整理しておく。どちらを呼ぶかは「read をまだ使うか」で決める。 USE CASE 3 複数スコープの一括格下げを安全に組み込む 課題 複数の write スコープをまとめて格下げしたいが、一部だけ反映される中途半端な状態は避けたい。 打ち手 複数スコープを 1 回の呼び出しで渡し、 userErrors が空かどうか、 downgraded に何が返ったかを確認する。 効果 1 件でも失敗すれば全体が拒否されるため、スコープ状態が部分的に変わることがない。 技術メモ 未付与の write は無視される（エラーにならない）ので、「渡したもの」ではなく downgraded の内容で結果を判定する。 9 提案で使える1行サマリ 「API 2027-01 から、アプリは任意の write スコープを対応する read スコープに格下げできる。 読み取りを残したまま書き込み権限だけを手放せる、最小権限化のための新 mutation。 既存アプリの対応は不要。必要になったアプリだけが使えばよい。」 source ： shopify.dev/changelog/downgrade-app-access-scopes-from-write-to-read 原文公開日 2026-10-07