Offline access tokens now support expiry and refresh

Offline access tokens now can optionally expire after 60 minutes and come with a refresh token. You can use the refresh token to obtain a new offline access token without requiring merchant interaction. This update aligns our process with the OAuth 2.0 specification and enhances security.

How expiry works

OAuth authorizes your app to act on behalf of a store. Once the merchant approves your requested scopes, you receive tokens.

1. Direct the merchant through OAuth and request offline access.
2. We provide:
   • access_token access token to be used to make API requests
   • expires_in time to live (TTL) of the access token in seconds (3600 seconds)
   • refresh_token used to request a new access token with an updated TTL
3. Before or after the access token expires, exchange the refresh_token at the token endpoint to receive a new offline access token.
4. Update stored tokens with the latest values returned by the refresh response.

Refer to the OAuth documentation for specific parameters, error codes, and retry guidance.

How to implement expiry

• Securely store refresh tokens, as they are sensitive credentials that can generate new access tokens. Use a secrets manager, encrypt at rest, and restrict access.
• To implement expiring tokens, you'll need to:
  • Track the access token’s 60-minute expiry.
  • Proactively refresh tokens a few minutes before they expire, and when you recieve a 401 response.
  • Update stored tokens with the latest values from the refresh response.
  • Remove any assumptions in your code that offline tokens never expire.
• Monitor logs and alerts for token refresh failures, and revert to a new OAuth authorization if necessary.

Migration and compatibility

• This change is additive: existing perpetual offline tokens will continue to function for now.
• Available with both token exchange and authorization code grant types. The client credentials grant already supports expiry and refresh using a slightly different OAuth 2 spec process.