Updated: 31 January 2022 - Action required - Deprecating persistent refresh tokens

Our earlier post, 31 January 2022 - Action required - Deprecating persistent refresh tokens has been a highly valuable collaboration with the Atlassian developer community. We’ve heard your feedback, and have made changes to the roll out plan for rotating refresh tokens. In case you missed some of the details in the discussion, we’ve highlighted the important parts in this post to get you up to speed.

What is changing?

We’re rolling out a breaking change for OAuth 2.0 integrations, migrating away from the persistent OAuth 2.0 refresh token to rotating refresh tokens.This affects all OAuth 2.0 integrations that use the offline_access scope to enable refresh tokens.

What are rotating refresh tokens?

Atlassian built on top of Auth0 to provide OAuth 2.0 authentication tokens. Rather than using a static refresh token value, the refresh token rotation feature ensures that for each token use, the refresh token value is rotated and previous token is invalidated. Learn how Auth0 implements refresh token rotation.

This has a number of implications for your OAuth 2.0 integrations you should be aware of:

  • Rotating refresh tokens expire after 90 days of user inactivity. Each time a new rotating refresh token is used, the inactive expiry time is reset to 90 days .
  • Once a token has been invalidated, it may not be re-used. Reuse of old tokens outside the leeway interval invalidates all refresh tokens, and requires the user to re-consent. The leeway interval is 10 minutes .
  • All tokens have an absolute expiry time of 365 days . After a year, users must re-consent, resetting the absolute expiry for another year. The absolute expiry time persists between token refreshes and cannot be reduced, or removed.

We’re aware that introducing an absolute expiry time is a limitation for some of your users and use cases. Currently, the absolute expiry is a requirement from Auth0 and an implementation limitation for our tokens. We’re working on a solution to remove the absolute expiry time requirement for tokens, and are aiming to remove this requirement. The expectation is that removing the requirement will not require reissuing tokens. While we can’t commit to a date at this stage, we are aiming to complete the migration in August 2022, way a head of the earliest time apps will experience an absolute lifetime token expiry (which will be December 2022).

See the OAuth 2.0 integration frequently asked questions for further details on token lifetimes and leeway time.

By when do I need to do it?

From Aug 4, 2021 persistent refresh tokens are deprecated. All new OAuth 2.0 integrations use rotating refresh tokens.

During the deprecation window you’re able to switch between both refresh token behaviors in the developer console.

From Jan 31, 2022 all OAuth 2.0 integrations must use rotating refresh tokens. In addition refresh token options in the developer console will be removed.

What do I need to do?

Firstly, consider if your app really requires offline_access . If your app requires ongoing access you’ll be able to work with both the persistent and rotating methods during the deprecation window.

Update your integration

Update your code to store the new refresh token values returned from https://auth.atlassian.com/oauth/token

An example response looks like:

HTTP/1.1 200 OK
Content-Type: application/json
    "access_token": <string>,    
    "refresh_token": <string>,
    "expires_in": <expiry time of access_token in second>,
    "scope": <string>

Enable rotating refresh tokens

Once your integration code is ready to handle rotating refresh tokens, enable them from the developer console, like this:

  1. Select your integration in the developer console.
  2. Select Authorization .
  3. Select Use rotating refresh tokens from the refresh token options.
  4. Save your changes.

Request a new refresh token

Once enabled in the developer console, your next access token request will trigger the migration process.

  1. Request a new access token using the persistent refresh token.
  2. Store the new refresh token value, this is a rotating refresh token and the persistent token is invalidated.
  3. Use the stored refresh token for the next access token request.

See how do I migrate from the persistent refresh token to rotating refresh token? for a code example and further details.

As always, if you have any questions please feel free to reach out to me here, submit a Dev Help ticket, email me on nnikolaevsky@atlassian.com, or book a call with via Calendly here.


1 Like

Thanks for the updated post and information, Nir.

We’re considering switching back to persistent tokens until closer to the deadline, just in case any new configuration issues are discovered. We’ll then switch back to rotating tokens before the deadline. After reading through Auth0 docs, it appears that transitioning between persistent and rotating tokens is seamless. Does that match your understanding too? Is there anything we’re missing or any strong reason we shouldn’t switch between the two configurations repeatedly?

@Nir Thanks for the new update and docs!

Quick question, we just noticed a refresh token issued just over 30 days ago (and used many times since) expired on 11/05/2021. Just verifying that from today forward, all refresh tokens issued will have the properties defined in the summary of this post. Most importantly, the absolute expiry is 1 year once the OAuth2 flow is initiated.


Hey @AtlassianIntegration, you’re right, you should be able to switch between persistent and rotating refresh tokens without any negative side effects.

The only thing I would be mindful of is not using old or expired refresh tokens as this could result in reuse detection and your users needing to re-consent (for example using a persistent refresh token after moving to rotating refresh token and getting a new token), but this is mentioned in the docs.

Hey @KevinGreenan,

Can confirm that both new apps being built/migrated to rotating refresh tokens and apps that already have been using them are now on the new config, including the 1 year absolute lifetime.

Great! Thank you @Nir !

This topic was automatically closed 30 days after the last reply. New replies are no longer allowed.

Hey everyone, the deprecation is starting today! From this point on we will progressively migrate all 3LO apps from persistent refresh tokens to rotating refresh tokens, plus remove the toggle in the developer console that allowed you to switch between the two.

If you encounter any problems please submit a Dev Help ticket , thank you!