Skip to main content
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.