A token is not a complete permission inventory
An application may hold a valid token and still lack permission for a particular Shopify API operation. Requested scopes, granted scopes, installation model, token type and resource access all matter. Replacing the token repeatedly without understanding those boundaries can disrupt working integrations and broaden access unnecessarily.
Shopify's documentation distinguishes standalone authorization flows from managed installation used by apps built with its tooling. Follow the flow appropriate to the actual app. This guide concerns permission reconciliation, not a universal instruction to force every merchant through a custom OAuth implementation.
Setup: map operations to minimum access
List the app, shop identity, API version, required operations and minimum scopes. Record how the installation declares and updates permissions. Compare the effective granted access with that contract using the supported API and installation evidence.
The reviewed standalone authorization documentation instructs applications to verify granted scopes rather than assuming the requested set was accepted. It also explains that additional scopes follow the appropriate reauthorization or managed-installation mechanism. Keep tokens and callback secrets outside logs and source control. A permission diagnosis should not require sending credentials through email or chat.
Illustrative incident: one new feature fails after deployment
An illustrative integration adds a feature requiring additional resource access. The code is deployed, but existing installations still have their prior grants. Old features work and the new operation fails. This is a teaching scenario, not a claim about a particular merchant or client.
Capture the sanitized API error, shop identity reference, app revision and required capability. Compare a newly authorized test installation with an existing one. Do not infer that a deployment automatically changed every merchant's permissions.
Troubleshooting: establish which contract differs
| Observation | Evidence | Investigation |
|---|---|---|
| New operation fails, old ones work | Required capability and granted scopes | Is an additional grant missing? |
| Only one shop fails | Installation identity and merchant approval | Does that installation have a different grant set? |
| Reauthorization appears successful but access is unchanged | App model and effective installation state | Was the correct update flow used? |
| Token is rejected broadly | Token lifecycle and app/shop association | Is this authentication rather than scope authorization? |
Do not request a broad collection of unrelated permissions merely to avoid future reviews. Explain the business purpose of each capability and retain a feature behavior for installations that have not granted optional access.
Corrective action and feature rollout
Use the supported scope-update path for the app's installation model. Verify the resulting grant before enabling the dependent operation. Keep the feature gated on actual capability so an existing merchant receives a clear action or limited experience rather than repeated unexplained errors.
Handle revocation and uninstall as lifecycle events. Stop work that no longer has authorization and reconcile pending operations according to the product's data-retention policy. A stored token must not become an excuse to continue using access after the installation's authority has changed. Audit changes without recording secret token values.
Verification, authorization objective and SOP
Test a fully authorized installation, one missing an optional grant, a rejected additional permission and a revoked installation. Confirm that unsupported operations fail safely while unrelated features remain usable. Review background jobs as well as interactive requests; both need the same capability awareness.
An internal SLO can measure successful authorized operations for installations meeting the documented prerequisites. Permission-denied responses should remain distinct from platform availability failures. A customer SLA needs explicit scope. The SOP should identify scope ownership, merchant communication, grant verification, token handling and revocation cleanup. Do not represent a declared scope as proof of merchant consent.
See Shopify development and cloud security.
Technical reference
Shopify standalone authorization and granted scopes, reviewed 19 October 2026. Follow documentation matching the installed product version.