important

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

Status

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

Status:: proposed
Deciders:: rishabhpoddar, porcellus
Proposed by:: porcellus
Created:: 2022-10-25
Last updated:: 2023-01-02

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.