Shopify requires expiring offline access tokens for all public apps by Jan 1, 2027 — what developers must do now

Table of Contents

1. Key Highlights
2. Introduction
3. What exactly is changing and when
4. Why Shopify is enforcing expiring offline tokens
5. How expiring offline access tokens work (technical overview)
6. Who must act (and who does not)
7. Migration checklist for public apps — practical step‑by‑step
8. Concrete implementation patterns and code considerations
9. Common pitfalls and how to avoid them
10. Real‑world examples and scenarios
11. Communication strategy for merchants and partners
12. Testing matrix and acceptance criteria
13. Monitoring and observability best practices
14. Consequences of non‑compliance and enforcement
15. Tools and resources
16. Long‑term implications for app architecture
17. Checklist for the next 60 days (pragmatic timeline)
18. FAQ

Key Highlights

• All public Shopify apps must use expiring offline access tokens when calling the Admin API starting January 1, 2027; apps that still use non‑expiring offline tokens after that date will receive authentication errors.
• This requirement extends the April 1, 2026 rule (which applied only to newly created public apps) to every public app, including those created before April 1, 2026; custom apps and merchant-created apps are not affected.
• Developers must migrate existing non‑expiring tokens to the new expiring token model (60‑minute lifetime with automatic rotation). Merchants do not need to reinstall apps — migration occurs via code using Shopify’s migration steps; use official libraries or templates where available.

Introduction

Shopify is closing a long‑standing security gap in how third‑party public apps authenticate to the Admin API. Non‑expiring offline access tokens can remain valid indefinitely if exposed, producing an enduring attack surface for merchant accounts. Beginning January 1, 2027, Shopify will require all public apps to switch to expiring offline access tokens that last 60 minutes and rotate automatically. Apps that fail to migrate will trigger authentication failures and lose API access.

This move standardizes token security across the platform and aligns Shopify with modern OAuth practice. For thousands of app developers, the change requires updating token storage, refresh handling, and background job design. The technical steps are straightforward for teams using Shopify’s official app templates and libraries, but some common pitfalls and operational impacts deserve careful planning. The following analysis explains what changes, why they matter, how the tokens work, and provides an actionable migration checklist, testing guidance, and troubleshooting advice.

What exactly is changing and when

Shopify requires public apps to stop using non‑expiring offline access tokens and to use expiring offline access tokens for Admin API requests starting January 1, 2027. The key points:

• Effective date: January 1, 2027.
• Scope: All public apps — including those created before April 1, 2026 — that currently authenticate to the Admin API using non‑expiring offline access tokens.
• Previously applied rule: On April 1, 2026 Shopify required expiring offline tokens only for newly created public apps. The January 1, 2027 change extends that requirement to every public app on the platform.
• Authentication behavior after the deadline: Any public app that continues to present a non‑expiring offline token when calling the Admin API will encounter authentication errors. Calls will fail until the app uses an expiring token or completes the migration.

Apps that are not affected:

• Custom apps created by or for a merchant.
• Apps created by merchants in the Dev Dashboard or in the admin directly.

Merchants will not need to reinstall a properly updated app. Migration is performed by the app developer through code that exchanges existing tokens and updates storage.

Why Shopify is enforcing expiring offline tokens

Non‑expiring tokens create a persistent risk. If a token leaks — through a repository push, a compromised server, or a misconfigured log — that token grants indefinite Admin API access until the developer or merchant manually revokes it. Expiring tokens shrink the attack window to the lifetime of the access token (60 minutes), and the refresh mechanism rotates credentials, reducing the likelihood that an exposed token remains a valid credential.

Technical and operational advantages:

• Credential rotation reduces long-lived exposure and makes retrospective damage control simpler.
• Uniform expiration enforces a predictable refresh flow developers can code against.
• Aligns with OAuth best practices used by other platforms: short-lived access tokens plus refresh tokens.
• Easier auditing: systems can monitor token rotation frequency and refresh failures as operational signals.

From a developer point of view, expiring tokens require implementing a refresh flow and secure storage for refresh tokens. For teams that use Shopify’s official app templates or API libraries, refresh handling may already be implemented; remaining work is typically a token exchange and storage migration.

How expiring offline access tokens work (technical overview)

Expiring offline access tokens follow the standard short‑lived access token and refresh token pattern. Essentials:

• Access token lifetime: 60 minutes. After expiration the access token will no longer authenticate Admin API calls.
• Refresh token: Delivered alongside the access token. The refresh token is used to request a new access token without user interaction.
• Rotation: Tokens rotate automatically as part of the refresh exchange. Each refresh may produce a new refresh token, requiring the app to update stored refresh tokens after each exchange.
• Automatic handling: Official Shopify SDKs and templates handle token refresh and rotation; custom implementations must manage refresh and persistent storage of the latest refresh token.
• Authentication errors: API calls using expired or revoked access tokens return standard 401/403 style authentication errors. Apps should detect these responses and perform the refresh flow.

Important conceptual differences from non‑expiring tokens:

• Non‑expiring tokens remained valid until explicitly revoked. Expiring tokens have a fixed lifetime and a refresh mechanism.
• With expiring tokens, developers must implement a small amount of state management: store the latest refresh token, detect failed requests, and handle token exchange before or after failures.

Behavior during migration:

• Shopify allows an app to exchange its existing non‑expiring offline token for the new expiring token through code. Merchants do not need to re‑authorize or reinstall apps, because the migration operation occurs server‑side.

Who must act (and who does not)

Affected:

• Public apps using non‑expiring offline access tokens for Admin API requests. That includes any public app, regardless of creation date, still relying on non‑expiring tokens as of January 1, 2027.

Unaffected:

• Custom apps created in a merchant’s admin or via the Dev Dashboard for a specific merchant.
• Merchant-created apps not distributed as public apps.

If your app already uses expiring offline tokens with a proper refresh implementation, no further action is required. If you are unsure, treat the app as affected and verify token types in your storage or logs.

Migration checklist for public apps — practical step‑by‑step

A concrete migration plan reduces surprises. The following checklist describes the most reliable approach for converting a public app from non‑expiring offline tokens to expiring offline tokens.

1. Inventory and assessment
   • List all shops your app is installed on and where the app stores tokens.
   • Identify where non‑expiring offline tokens are persistently stored (databases, secret stores).
   • Catalog background processes, workers, cron jobs, and scheduled tasks that currently use non‑expiring tokens.
   • Note integrations that share tokens with other services.
2. Read the migration guide and align dependencies
   • Review Shopify’s migration guide for the precise steps and current endpoints (Shopify provides a step‑by‑step guide and examples).
   • Upgrade to the latest official Shopify libraries or app templates where possible. These often include refresh handling and abstract away token rotation.
3. Implement server‑side token exchange
   • Implement code to exchange existing non‑expiring offline tokens for expiring offline tokens. The exchange occurs without merchant reauthorization.
   • Store the refresh token securely and replace non‑expiring tokens in your database.
   • Ensure your storage model can accommodate token expiration timestamps and the current refresh token value.
4. Add token refresh flow and rotation handling
   • Implement a refresh flow that runs on demand (on authentication failure) and optionally preemptively (just before expiry).
   • After each successful refresh, update stored tokens with the newly returned refresh token if the system rotates refresh tokens.
   • Protect concurrent refreshes with locking to avoid race conditions where multiple processes attempt refresh simultaneously.
5. Update background processors and long‑running jobs
   • For background jobs that may run longer than 60 minutes, obtain a fresh access token at job start and refresh it if the job exceeds the token lifetime. Alternatively, design jobs to checkpoint and re-acquire credentials at safe intervals.
   • Batch processors or bulk syncs should request tokens at the start of the operation; when jobs are distributed, ensure every worker has access to the current refresh token.
6. Testing and staging
   • Deploy changes to a staging environment with test shops or sandbox accounts. Simulate token expiry and validate refresh exchange behavior.
   • Force accelerated expiry or use dev tokens with shorter lifetimes to test rotation logic.
   • Verify that edge cases — network failures, concurrent refresh attempts, and expired refresh tokens — are handled gracefully.
7. Rollout strategy
   • Perform a canary rollout to a small percentage of shops to catch unforeseen errors.
   • Monitor authentication errors, failed refresh attempts, and merchant support tickets during the canary period.
   • Gradually increase the rollout based on stable metrics.
8. Merchant communication and support
   • Prepare concise messaging for merchants explaining they do not need to reinstall the app.
   • Provide contact paths for merchants if they notice degraded functionality or API errors.
   • Log and report any installs where migration fails and require follow-up actions.
9. Post‑migration audit
   • Confirm that every shop no longer stores non‑expiring tokens. Update records to show migration status per shop.
   • Audit logs for refresh frequency and token rotation anomalies.
10. Monitor and alert

• Create alerts for elevated 401/403 rates, refresh failures, and unexpected token revocations.
• Track refresh success ratio and time to recovery after refresh failures.

Concrete implementation patterns and code considerations

The exact implementation depends on your stack; below are general patterns and specific considerations for common problems.

Token storage and schema:

• Recommended fields: shop_id (or shop domain), access_token, refresh_token, token_expires_at (timestamp).
• Encrypt refresh tokens at rest and restrict access in the application’s secrets/storage layer.
• Use database transactions or optimistic concurrency control when updating tokens to avoid race conditions.

Refresh flow triggers:

• Lazy refresh: attempt API call, if it fails with an authentication error, call the refresh endpoint and retry.
• Proactive refresh: check token_expires_at and refresh a few minutes before expiry to avoid request failures during peaks.
• Hybrid approach: combine proactive refresh with lazy retry for robustness.

Concurrent refresh prevention:

• Use a distributed lock (Redis lock, database lock record) keyed by shop to ensure only one process performs refresh at a time. Other processes should wait for the refresh result or read the updated token.

Handling rotating refresh tokens:

• Some refresh flows return a new refresh token with each refresh. Replace the stored refresh token immediately after receiving the new one.
• If refresh fails because the stored refresh token is invalid, trigger a reauthorization flow for that shop if necessary.

Long‑running tasks:

• Acquire a fresh access token at the start. If tasks exceed the token lifetime, refresh mid‑job or split the job into smaller units.
• For critical operations that cannot be interrupted, consider creating checkpoints and resuming after a refresh.

Retry and backoff:

• Use exponential backoff for refresh attempts when facing temporary network errors.
• Limit total retries and escalate to human intervention or merchant reauthorization if refresh repeatedly fails.

Logging and observability:

• Log refresh requests and their outcomes, but never log refresh tokens or access tokens in plaintext.
• Instrument the number and frequency of refreshes to detect anomalies such as token churn or abuse.

Libraries and frameworks:

• If you rely on official Shopify libraries or app templates, review their documentation and configuration to ensure refresh handling is enabled.
• For custom SDKs, implement the refresh logic described above and ensure tests cover concurrent refresh scenarios.

Example workflow (abstracted)

1. App detects token_expires_at is within five minutes or receives a 401.
2. App attempts to acquire a distributed lock for the shop.
3. If lock acquired, call the token refresh endpoint using the stored refresh token.
4. On success, update stored access_token, refresh_token, token_expires_at.
5. Release the lock. Retry the original API request with the new access token.
6. If refresh fails with an unrecoverable error, mark the shop as needing reauthorization and notify support.

Common pitfalls and how to avoid them

Many migration failures stem from predictable mistakes. Anticipate and preempt them.

Pitfall: Forgetting to update background jobs

• Symptom: Background tasks that run periodically or for extended durations begin receiving 401 errors after expiration.
• Fix: Ensure all job workers use the stored refresh token to obtain a fresh access token at job start or implement mid-job refresh checkpoints.

Pitfall: Race conditions during refresh

• Symptom: Multiple workers detect expiry and simultaneously request refresh, potentially causing unpredictable outcomes or invalid refresh tokens.
• Fix: Implement a per‑shop locking mechanism. Allow other processes to wait for or read the updated token instead of triggering parallel refreshes.

Pitfall: Not storing the rotated refresh token

• Symptom: App refreshes once or intermittently, then fails because subsequent refresh requests use the old refresh token.
• Fix: After every successful refresh, atomically overwrite the stored refresh token. Treat the refresh token as stateful.

Pitfall: Logging secrets

• Symptom: Accidental exposure of refresh or access tokens in logs, which creates immediate security risks.
• Fix: Mask or avoid logging tokens. Log only token events (success/failure) with non‑sensitive identifiers.

Pitfall: Assuming merchants must reinstall

• Symptom: Developers instruct merchants to reinstall unnecessarily, creating support friction.
• Fix: The migration can happen server‑side; reserve reinstallation or reauthorization for rare edge cases where refresh tokens become invalid and cannot be recovered.

Pitfall: Outdated SDKs and templates

• Symptom: Older SDKs may not support the new token rotation model.
• Fix: Upgrade to the latest Shopify libraries and verify refresh flows work in staging.

Real‑world examples and scenarios

Two illustrative scenarios highlight the risks and the migration impacts.

Scenario 1 — Preventing a long‑running breach ShopCartPro, a public app with 5,200 merchant installs, used non‑expiring tokens. A developer unintentionally pushed credentials to a public GitHub repo. An attacker found the token and began querying orders across several stores. Because the tokens never expired, the attacker retained access for days until detection. After Shopify’s expiring token model, a leak like that would have limited the window to 60 minutes; rotation would have invalidated the exposed credential after its next refresh cycle. ShopCartPro would need only to detect a suspicious refresh pattern rather than perform a full manual revocation across thousands of shops.

Scenario 2 — Migration done well AnalyticsPlus, a SaaS analytics provider, uses Shopify’s official app template. The team followed the migration checklist: upgraded libraries, deployed a token exchange job that migrated stored tokens, implemented distributed locks, and updated background jobs to request fresh tokens at job start. They performed a canary rollout to 50 shops. Metrics showed no increase in 401 errors and refresh success rates above 99.9%. They rolled out the migration to all shops in two weeks with no merchant reinstallation or downtime.

Scenario 3 — Background job oversight leads to outages InventorySync relied on a nightly, four‑hour bulk sync that started at midnight and used a single access token acquired at job start. After migration, the token expired in the middle of the sync and the job failed repeatedly, leaving inventory out of date for several stores. The fix was to refresh tokens mid‑job and to split lengthy operations into smaller tasks that checkpoint state and re‑acquire credentials.

Communication strategy for merchants and partners

Good communication reduces merchant confusion and support load. Points to cover in merchant-facing messages:

• Reassurance: Merchants do not need to reinstall the app.
• Why the change: Brief, customer‑facing security explanation (shorter token lifetimes reduce risk).
• Expected impact: No action required from merchants; minimal to no downtime if the developer follows the migration process.
• Support channels: Clear contact paths if merchants notice problems.

Sample merchant message (concise) "Security update: We’re updating how our app authenticates with Shopify to improve protection of your store data. No action required from you — we’ll handle the update server‑side. If you notice any problems, contact support."

For partner communication (other developers or integrators), provide technical release notes that include:

• Migration schedule and milestones.
• Known compatibility changes.
• Contact for escalations and sample code snippets.
• Testing instructions and failure modes to watch.

Testing matrix and acceptance criteria

Testing reduces the chance of regressions. Use the following matrix for acceptance criteria.

Functional test cases:

• Exchange non‑expiring token for expiring token successfully for a shop.
• Successful API call using newly acquired expiring token.
• Automatic refresh on 401 response and subsequent API call success.
• Proactive refresh just before expiry prevents 401 responses.
• Token rotation correctly updates stored refresh token after each refresh.
• Concurrent requests do not cause multiple simultaneous refreshes.
• Background jobs refresh mid‑job and complete successfully.

Failure mode tests:

• Simulate network timeouts during refresh — ensure exponential backoff and eventual success or controlled failure.
• Simulate invalid refresh token — ensure the shop is marked for reauthorization and support is notified.
• Simulate database write failures when storing refreshed tokens — ensure you can retry and avoid half‑updated state.

Operational acceptance:

• Monitor shows refresh success rate ≥ 99.9% for canary shops.
• No increase in merchant support tickets related to authentication.
• Alert thresholds configured for elevated 401 rate and refresh failure spikes.

Monitoring and observability best practices

Visibility into token lifecycle helps detect problems early.

Essential metrics:

• Refresh request rate and success rate.
• Number and rate of 401/403 responses per shop.
• Time between refresh attempts and average refresh duration.
• Count of shops requiring reauthorization.

Alerts:

• Spike in 401 responses for a single shop or across the fleet.
• Refresh success rate below a set threshold (for example, 99% over five minutes).
• Rapid increase in refresh frequency for a single shop (could indicate abuse or automation bug).
• Unsuccessful token storage events or encryption failures.

Logs:

• Log refresh attempts and outcomes as structured events.
• Include non-sensitive IDs (shop domain, job ID) for correlation.
• Redact or avoid logging token values.

Audit data:

• Keep an audit trail of token exchanges and replacements with timestamp and acting service account for forensic purposes. Protect the audit trails with appropriate access controls.

Consequences of non‑compliance and enforcement

After January 1, 2027, public apps that call the Admin API with non‑expiring offline tokens will receive authentication errors and lose access to the API until they migrate. Developers who delay migration risk:

• Interrupted service for merchants that rely on the app.
• Increased merchant support requests and negative reviews.
• Potential loss of revenue and reputational damage if integrations fail during a busy period.

Shopify will enforce the requirement platform‑wide. Developers should prioritize migration well in advance of the deadline, perform staged testing, and have fallbacks if a subset of shops fails migration.

Tools and resources

• Shopify migration guide for offline access tokens: Consult Shopify’s official migration documentation for the exact endpoints, request/response formats, and sample code (available on Shopify’s developer docs).
• Shopify official SDKs and app templates: Upgrade to the latest versions to inherit refresh handling.
• Dev platform community forums: Post questions and share experiences with other developers if you encounter unusual cases.
• Internal checklists and runbooks: Prepare incident runbooks for token refresh failures, reauthorization workflows, and merchant communication.

Long‑term implications for app architecture

The change nudges teams toward more robust authentication and operationally resilient app architectures:

• Token lifecycle management becomes an ingrained part of app design. Future features should presuppose short‑lived credentials.
• Background job design will evolve to accommodate credential expiry; long job strategies will lean toward smaller, restartable units of work.
• Observability and security posture improve through token rotation metrics.
• Teams may adopt ephemeral credentials more broadly, using short lifetimes for other service tokens too.

Treat the migration not as a one‑off compliance task but as an opportunity to harden infrastructure, increase automation around credentials, and reduce long‑term risk to merchants.

Checklist for the next 60 days (pragmatic timeline)

If the January 1, 2027 deadline is looming for your release cadence, use this timeboxable plan.

Days 0–7: Assessment and planning

• Inventory shops and tokens.
• Identify apps and services that hold tokens.
• Upgrade test dependencies (official libraries, templates).

Days 8–21: Implement migration and refresh logic

• Implement server‑side token exchange code.
• Add refresh endpoints and token storage updates.
• Implement locking and concurrency controls.

Days 22–35: Testing and staging

• Perform unit and integration tests.
• Run staging migrations and simulate expiry cases.
• Validate background job behavior.

Days 36–49: Canary rollout and monitoring

• Roll out to a small set of shops.
• Monitor metrics and logs.
• Resolve issues and refine alerts.

Days 50–60: Full rollout and audit

• Complete fleet migration.
• Audit all shops to confirm no non‑expiring tokens remain.
• Finalize merchant communications and runbook.

This schedule compresses work into two months. Adjust based on team size and complexity.

FAQ

Q: What is the deadline for switching to expiring offline tokens? A: January 1, 2027. After that date public apps using non‑expiring offline tokens for Admin API calls will receive authentication errors.

Q: Does this affect custom apps or apps created in merchant admin? A: No. Custom apps and merchant‑created apps in the Dev Dashboard or admin are not affected by this change.

Q: Do merchants need to reinstall the app? A: No. Developers can migrate tokens server‑side using the exchange process Shopify provides. Reinstallation is not required for a successful migration in typical cases.

Q: What happens if my app still uses non‑expiring tokens after the deadline? A: API calls will fail with authentication errors. The app must implement the expiring token model and exchange tokens to restore access.

Q: How long is the new access token valid? A: The expiring offline access token has a 60‑minute lifetime.

Q: How should refresh tokens be stored? A: Store refresh tokens securely: encrypt at rest, restrict access, and never log tokens. Use a secure secret store or database with strict access control. Replace stored refresh tokens immediately when a new one is issued.

Q: Do refresh tokens rotate? A: Yes. The refresh exchange may return a new refresh token. After each refresh, update the stored refresh token. Your implementation must handle rotation.

Q: How should I handle background jobs or long‑running processes? A: Obtain a fresh access token at job start and refresh when necessary. Break long jobs into smaller, checkpointed units that re‑acquire tokens to avoid mid‑job expiry issues.

Q: What if refresh fails or the refresh token becomes invalid? A: Mark the shop as needing reauthorization and notify the merchant or support team. Implement retry with exponential backoff for transient errors. If refresh consistently fails, trigger a merchant re‑auth flow.

Q: Are there official libraries that handle refresh automatically? A: Shopify’s official app templates and SDKs include refresh handling in many cases. Upgrade to the latest templates and verify behavior for your stack.

Q: How do I test migration safely? A: Use staging shops or developer stores. Force token expiry to test refresh behavior. Simulate failure modes such as network timeouts and invalidated refresh tokens.

Q: What monitoring should I add? A: Track refresh success rates, 401/403 responses, refresh frequency, and reauthorization counts. Alert on spikes in authentication failures and refresh failures.

Q: Who can I contact for help? A: Use Shopify’s developer documentation and the dev platform community forums to ask questions or seek guidance. Prepare detailed logs (without tokens) when posting issues.

Q: Will Shopify automatically migrate tokens for me? A: No. The responsibility for migrating tokens rests with each app developer. Shopify provides guidance and APIs to perform the exchange.

Q: Can I delay migration until after January 1, 2027? A: Delaying risks service interruption due to authentication errors. Begin migration early to allow time for testing, canary rollouts, and incident response.

Q: How do I handle concurrent token refreshes safely? A: Implement a per‑shop locking mechanism (Redis lock, database lock). Ensure only one process performs refresh at a time and others wait for the updated token.

Q: If I use multiple services that share tokens, how should I coordinate? A: Centralize token storage in a secure service and expose token retrieval APIs to other services. Enforce access controls and ensure all services read the latest refresh token.

Q: What are the security benefits in practice? A: Short‑lived access tokens reduce the effective window of compromise and make credential rotation and detection simpler. They limit ongoing risk from leaked tokens and align your app with OAuth best practices.

Q: Where can I find the migration guide and API docs? A: Shopify’s developer documentation includes an offline access tokens migration guide and examples. Consult the official docs for exact endpoints and sample requests.

If you have questions specific to your app’s architecture or encounter unusual behavior during migration, gather non‑sensitive logs and error samples and reach out in Shopify’s developer community for targeted advice.