Refresh Token Handling - Refresh Token Handling for API Providers and Consumers

Background
The API Centre received a query about a failure that occurs when refresh token rotation is used. An API Provider processes a refresh request, issues a new access token and refresh token, and invalidates the previous refresh token. If the API Consumer does not receive the response because of a network outage or timeout, it still holds only the previous refresh token. A standard assumption would be that token is no longer valid, so any retry would fail. In this situation the API Consumer cannot obtain an access token, even though the consent remains valid.
The standards do not require refresh token rotation and do not define recovery behaviour for this failure. The only recovery path defined is consent re-authorisation, which requires the customer to return and authorise again. This guidance sets out how to avoid the failure.

Basis
FAPI 2.0 updates the security profile, stating that authorization servers "shall not use refresh token rotation except in extraordinary circumstances." NOTE 1 explains that rotation "does not provide security benefits when used with confidential clients and sender-constrained access tokens," while causing "user experience degradation and operational issues whenever the client fails to store or receive the new refresh token and has no option to retry."
This reasoning applies to the NZ ecosystem. FAPI 2.0 is the intended future standard, so the guidance aligns with it now. Providing this guidance does not contradict current standards; it clarifies areas that are open to interpretation.

Guidance

1. Do not rotate refresh tokens
   API Providers should return the same refresh token in each refresh response and should not invalidate it on use. This removes the failure described in section 1 entirely: the API Consumer always holds a token the API Provider still accepts, so a lost response causes no harm and the request can simply be retried.

2. Where rotation cannot be avoided, provide an overlap

   Rotation may be necessary for infrastructure migration or similar situations. When used, the previous refresh token should remain valid briefly after rotation, allowing an API Consumer that missed the response to retry.

   The failure happens during a refresh initiated by the API Consumer, so it can detect the failure immediately and retry promptly. The overlap should cover the API Consumer's typical cycle. Hours should suffice for most implementations.

   If the previous refresh token is presented during the overlap, the API Provider should return the existing refresh token instead of rotating again. This lets the API Consumer recover the missed token and prevents multiple divergent tokens from one failure.

   API Providers should document the overlap they implement.

3. Refresh token expiry
   API Providers should adopt one of the following.
   Option A: expiry follows the consent. The refresh token expires when the consent expires. Where the consent is open ended, the refresh token does not expire, signalled by setting https://www.apicentre.paymentsnz.co.nz/refresh_token_expires_at to the end of the UNIX epoch (19 January 2038) as described in the standards. The token lasts as long as the authority it represents.
   Option B: sliding expiry. The refresh token expiry is set to the earlier of one year from now, or the consent expiry, and is recalculated each time the token is used. Where the consent is open ended, the expiry is one year from last use. A consent that continues to be used renews indefinitely. A consent that is abandoned lapses within a year, which gives the API Provider a means of clearing tokens that are no longer exercised.

4. API Consumers must not assume refresh tokens are static
   Rotation remains permitted, and expiry behaviour varies between API Providers. An API Consumer should persist the refresh token returned in each token response, whether or not it differs from the one held, and treat refresh_token_expires_at as authoritative rather than relying on a previously received value.
   
   

References