important

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

New built in claim expressing intent to link an account

Status:: accepted
Deciders:: rishabhpoddar, bhumilsarvaiya
Proposed by:: rishabhpoddar
Created:: 2022-11-30
Last updated:: 2022-12-01

Context and Problem Statement#

We need to verify email B even if logged in using email A, cause post login account linking may require you to verify email B in order to link it. For this to happen, we need a way for email verification related UI and APIs to know about email B

Considered Options#

Update accessToken payload email verification claim to have additional information regarding email B (email for which email verification needs to be done)
Add a new session claim that marks the session as "intent to link an account"
The frontend will send the recipeUserId to the backend during email verification APIs. So instead of the backend taking a session as input, they will take a recipeUserId + session as an input.

Decision Outcome#

Option chosen: Add a new session claim that marks the session as "intent to link an account"

This claim will be added during:

Post login account linking API in case email verification is required for the to link account.
In sign up related APIs like createCodePOST for passwordless if this is called with an input session.

New payload structure:

{
   "st-acc-to-link":{
      v: <recipe user ID> | "",
      t: ....,
   }
}

The v will be "" if this claim is being added in APIs like createCodePOST and the user does not exist. Else it will be the recipeUserId of the new user.
The email verification UI on the frontend and related APIs (create and consume verification code + is email verified API), check if this claim is present if the EmailVerificationClaim value is true. If this claim exists, and has a user ID, then it will use that for its operations.
This implies that the user will still be able to use their app routes and app's APIs even if the new account to link is kept in unverified mode.
This claim is removed when the account to link is either no longer a candidate for linking to the current session's account, or has already been linked.

This claim should also be used by passwordless login screen (like OTP or enter email / phone screen) so that they do not redirect to the / route in case a session exists, and this claim exists as well.

Pros and Cons of the Options#

Update accessToken payload email verification claim to have additional information regarding email B (email for which email verification needs to be done)#

This requires changing the base claim structure.

Add a new session claim that marks the session as "intent to link an account"#

Is more generic and can be used for purposes other than for email verification

The frontend will send the recipeUserId to the backend during email verification APIs. So instead of the backend taking a session as input, they will take a recipeUserId + session as an input.#

Intre=oduces complexity for users who are building their custom UI - they would have to manually pass the correct user ID.