Feature Request: Support for expiring offline access tokens and the token exchange grant

Overview

Request to add support for the OAuth 2.0 Token Exchange grant and the expiring-offline-access-tokens model (refresh tokens, refresh-token grant, session fields for refresh state) to the PHP SDK, bringing parity with @shopify/shopify-api (JS) which already exposes auth.tokenExchange() and associated plumbing.

Type

• New feature
• Changes to existing features

Motivation

Following up on #342, which was automatically closed in July 2024 without maintainer engagement. That predates the Shopify platform changes below; opening a fresh issue rather than reopening since the context has materially shifted.

In December 2025, Shopify announced that offline access tokens now support expiry + refresh (changelog). The follow-on April 1, 2026 requirement makes expiring offline tokens mandatory for new public apps. While no timeline for retiring permanent tokens for grandfathered apps has been announced, that is a logical next step.

When #342 was filed, token exchange was a convenience over the authorization-code-grant flow. It is now the acquisition path for the new expiring-offline-token grant type, and refresh-token handling is not optional for new public apps.

As of v6.1.1, the PHP SDK has no TokenExchange helper, no refresh_token / refresh_token_expires_at fields on Session, no parsing of expires_in / refresh_token / refresh_token_expires_in in OAuth::callback or AccessTokenResponse, and no grant_type=refresh_token helper - features all present in JS @shopify/shopify-api via auth.tokenExchange() and related APIs.

PHP apps building for the new model have to implement custom code for the token-exchange acquisition grant (online and offline, with optional expiring=1), the non-expiring-to-expiring migration exchange, and the refresh grant with single-use-refresh-token collision handling - plus carrying refresh-token state somewhere out-of-band from Session.

Is official PHP SDK support for token exchange + expiring offline tokens on the roadmap now? If maintainers are open to it but unstaffed, community contribution via PR may be viable - a clear statement either way would help app teams plan their implementations.

Thank you.

Start by comparing the PHP SDK's Session, OAuth::callback, and AccessTokenResponse with the existing @shopify/shopify-api auth.tokenExchange() APIs. Define the required token-exchange and refresh-grant behavior, including refresh-token session state and single-use collision handling; done means the PHP SDK supports the listed acquisition, migration, parsing, and refresh flows.