So you want to touch JWTs?

Many changes related to JWTs, even those made outside of 2U/edX, will still affect 2U/edX once merged. This may affect monitoring and communication, and this document contains some 2U/edX specific details for this reason.


It is easy to cause issues when making changes to JWTs. This document is a place where we can capture things you should think about or be aware of when making these changes.

Understanding JWTs

If you need general background of JWTs, you can first learn what is a JWT and decisions around OAuth2 and JWTs in the Open edX platform in OEP-42: Authentication.

Known Authentication Challenges

If you want to make any change safely, having some awareness of known challenges may help you understand how to make your change safely.

Rolling out JWT changes, including expiration

  • Reminder that JWT tokens are requested by third-parties, so you’ll need to pay extra attention when monitoring and communicating around changes that may affect these tokens.

  • Reminder that client credential JWTs used for server-to-server calls are cached in each service. We've seen issues during rollout that weren’t seen until these JWTs expire and new ones are requested.

  • Reminder of the current inconsistency around JWT creation and decoding documented under known challenges. This can easily cause problems where you least expect it.


See page warning for explanation for including 2U/edx specific information.

Communication of changes

See page warning for explanation for including 2U/edx specific information.

  • Communicate any changes to support.

    • Although problems are likely to affect authentication, we’ve seen a variety of issues that did not obviously relate to JWT changes, at least at first. Ensure that any new support issues in the following day are tracked back to a start time to see if it aligns.

  • Potentially provide early warning to partners (e.g. enterprise or other third-party users using JWTs) for certain types of changes.

  • Communicate any changes to warroom for visibility.