Multi-channel

Token expiry and refresh across four marketplace APIs

Token handling is the least interesting part of an integration and the most common single cause of one silently stopping.

Two tokens, two lifetimes

Almost every marketplace API uses the same pattern: a short-lived access token used on each call, and a longer-lived refresh token used to obtain new access tokens.

The access token expiring is routine and expected. The refresh token expiring is the one that requires a human to reauthorise, and it is the one that breaks things properly.

The failure everyone hits first

An integration fetches a token at startup and uses it thereafter. It works perfectly in testing, because testing takes minutes. It fails an hour after deployment, and the error looks like an authorisation problem rather than a design problem.

Refresh on a schedule ahead of expiry, not reactively when a call fails.

Refresh tokens expire too

This is the part that surprises people. A refresh token is not permanent. Some expire on a fixed schedule, some expire after a period of non-use, and some are invalidated when rotated.

If your integration goes quiet over a holiday and comes back to find the refresh token dead, that is not a bug - it is the documented behaviour of an unused credential.

Rotation is easy to get wrong

Several APIs issue a new refresh token each time you use the old one, and invalidate the old one immediately. If you refresh and fail to persist the new value, the next refresh uses a token that no longer exists.

The dangerous version is a partial failure: you refresh successfully, get a new token, and crash before saving it. You are now permanently locked out with no error to point at.

Persist the new refresh token before doing anything else with the response.

What to build

• Refresh well before expiry, on a timer
• Persist new refresh tokens immediately and atomically
• Alert when a refresh fails, because it will not fix itself
• Record when each connection was last successfully refreshed
• Make reauthorisation a one-click path, because you will need it

Multi-channel makes it worse

Four marketplaces means four credential sets per store, each with its own lifetimes and its own failure mode. Across several stores that is dozens of credentials, and the first sign one has died is usually a seller asking why their orders stopped.

A single view showing every connection and when it last refreshed successfully is worth building before you need it. After a silent failure, it is worth having had.

---