Skip to main content

This is a contributors guide and NOT a user guide. Please visit these docs if you are using or evaluating SuperTokens.

Deprecate JWT option once the access token is a proper JWT itself


This is just a proposal so far, it hasn't been accepted and needs further discussion.

rishabhpoddar, porcellus
Proposed by:
Last updated:

Context and Problem Statement#

We want to make our access token into a valid JWT. So, in the future the jwt setting will be "replaced" with just setting the auth mode to header. We need to decide a deprecation/migration path.

Considered Options#

  • Add deprecation warning if the jwt setting is turned on.
  • Keep the jwt option.

Decision Outcome#

Once we make the entire access token into a JWT:

  • Add deprecation warning with a migration link and set exposeAccessTokenToFrontendInCookieBasedAuth to true. See here
  • Add a function to the FE to access the entire access token as a string.
  • Since the access token can now be used instead of the a separate JWT embedded in the access token, it is more useful to send to third-party APIs where we are not intercepting request.
    • These will check the access token based on the JWKs endpoint exposed by the BE, but we do not need to worry about key rotation here, since the signing keys stay in the output of the jwks endpoint long after the access token expires.
    • Calling getAccessToken will cause a refresh to happen if the locally stored access token is expired, so refreshing should happen automatically in most cases (if the access token doesn't expire during the request) even if we are not intercepting requests to the domain.
    • Claim checking needs to be done manually in this case (e.g.: an API Gateway will not check if the email is verified or not). This should be documented/communicated somewhere.

Until then: the auth mode and jwt options are entirely independent, the jwt can be accessed through the access token payload in both auth modes.

Looking for older versions of the documentation?
Which UI do you use?
Custom UI
Pre built UI