Simple Guide to Shopify Expiring Access Tokens

Shopify is transitioning all public apps to use expiring offline access tokens. All existing public apps must adopt this new model before January 1, 2027 to prevent authorization failures.

This guide explains how this security update works, what will affect your application, and how to handle the changes in simple, clear terms.

1. How the Rotating Key System Works :

Instead of having a single permanent keycard that lasts forever, your app will now use two rotating keys:

The Access Key (1-Hour Life): The active key used to make calls to Shopify. It expires after 1 hour. Your app must swap it for a new one before it expires.

• The Refresh Key (90-Day Inactivity Window): A secondary key used to request the next 1-hour access key. Every time your app performs a refresh, Shopify resets this 90-day timer.

• The Expiration Rule: If your app does not call the Shopify API or refresh its credentials for 90 consecutive days, the connection expires completely. The merchant will need to log back into the app to restore access.

2. What Will Affect Your App & How to Handle It :

To ensure a smooth migration, both app owners and developers need to understand three key scenarios, what they affect, and how to handle them:

A. Multiple Actions Happening at the Same Time

• What affects us: If a store initiates multiple API requests or background updates at the exact same moment, the app might try to refresh the access key twice. Because Shopify invalidates the old key immediately upon rotation, the second request will fail with an authorization error.

• How to handle it: Ensure the app’s code uses a locking mechanism (like a per-store mutex or lock). Only allow one process to refresh the key at a time, while other parallel requests wait and read the updated key from the database.

B. Delayed Background Tasks

• What affects us: Background sync jobs are often queued up to run later. If a job is passed an access key as a parameter, that key may expire or rotate by the time the job actually runs, causing the job to fail.

• How to handle it: Never pass raw access keys directly into background job parameters. Pass only the store’s ID. The background task should always fetch the latest active key from the database right before calling the Shopify API.

C. Inactive Stores (The 90-Day Limit)

• What affects us: If an app is installed but the store goes completely silent (no user logins or background syncs) for 90 days, the connection expires.

• How to handle it:

  1. Preventive: Set up a routine scheduled task to automatically refresh the credentials of your active stores at least once a month. This keeps the 90-day sliding window active.

  2. Recovery: If a store does expire, detect the invalid key and show a clear, friendly prompt on the dashboard when they next visit, guiding them to re-verify the connection.

• Step-by-Step Rails Migration & Support: If your app is built on Ruby on Rails, read our technical Step-by-Step Rails Implementation Guide to update your migrations, gem dependencies, and initializers. If you need assistance or have questions, please reach out to our team directly.

• Official Shopify Developer Documentation: For technical specifications and API references on the token rotation APIs, consult the Shopify Dev: Explaining Expiring Access Tokens.