アクセス権限をWriteからReadへダウングレード

11月 02, 2026

APP PERMISSIONS

アクセス権限をWrite→Readへ安全にダウングレード

Admin GraphQL API 2027-01で追加されたappDowngradeAccessScopesで最小権限原則を実現

Admin GraphQL API 2027-01 以降、Shopify管理インストールを利用するアプリは appDowngradeAccessScopes ミューテーションを呼び出すことで、不要になった書き込みスコープを対応する読み取りスコープへ安全に切り替えられます。既存アプリへの追加対応は不要です。このミューテーションは呼び出し元アプリのインストールにのみ影響します。

1Before / After：権限変更の仕組み

2業務で使える具体ユースケース

課題: 商品データを表示するダッシュボードアプリが、初期実装の名残りで write_products を保持しており、マーチャントから「なぜ書き込み権限が必要なのか」と不信感を持たれている。
打ち手: appDowngradeAccessScopes(scopes: ["write_products"]) を呼び出し、read_products のみに縮小する。
効果: マーチャントへの権限説明が簡素化され、インストール承認率・信頼度が向上する。
技術メモ: write_products は optional_scopes に宣言されている必要がある。required_scopes に含まれている場合はダウングレード不可。

課題: 注文データの読み取りと書き込みの両方をリクエストしていたが、機能改修により読み取りのみで十分になった。しかし appRevokeAccessScopes で write_orders を剥奪すると、暗黙付与されていた read_orders まで失われてしまう。
打ち手: appRevokeAccessScopes の代わりに appDowngradeAccessScopes を使い、読み取り権限を維持したまま書き込みだけ返却する。
効果: 既存の注文一覧表示機能を壊さずに、最小権限原則を満たすことができる。
技術メモ: 公式ドキュメントによると appRevokeAccessScopes は書き込みスコープ経由でのみ付与されていた読み取りスコープも一緒に削除する仕様。ダウングレードとリボークは用途が異なるため注意。

課題: セキュリティ審査でアプリの保有スコープが過剰と指摘された。段階的に権限を縮小したいが、ユーザー再認証（OAuth再認可）を強いることなく対応したい。
打ち手: バックグラウンドジョブや管理画面の操作起点で appDowngradeAccessScopes を呼び出し、不要になったオプション書き込みスコープを順次読み取りへ変換する。
効果: ユーザー体験を損なわずに権限を縮小でき、SOC2やISMSなどセキュリティ要件への対応コストを削減できる。
技術メモ: バリデーション失敗が1件でもあるとリクエスト全体が却下される（アトミック操作）。userErrors を必ずチェックし、失敗時は対象スコープを絞り込んで再試行すること。

3技術者が押さえるべきポイント

項目	詳細
対象APIバージョン	Admin GraphQL API 2027-01 以降。それ以前のバージョンでは利用不可。
前提条件	Shopify管理インストール（Shopify-managed installation）を使用しているアプリのみ対象。
スコープ要件	対象スコープは `optional_scopes` に宣言されていること、かつ対応する読み取りスコープが存在する書き込みスコープであること。`required_scopes` はダウングレード不可。
アトミック性	リクエストに含まれるスコープのいずれか1つでもバリデーション失敗すると、リクエスト全体が拒否されインストールのスコープは変更されない。
revokeとの違い	`appRevokeAccessScopes` で書き込みスコープを削除すると、そのスコープ経由でのみ付与されていた読み取りスコープも一緒に失われる。読み取りを残したい場合は必ず `appDowngradeAccessScopes` を使うこと。
既存アプリへの影響	元記事に「No action is required for existing apps」と明記。既存アプリが壊れる変更ではない。
レスポンス確認	`downgraded` フィールドで変更成功したスコープ一覧を、`userErrors` でバリデーション失敗の詳細を確認できる。