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.

Expose all access token claims to the FE


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

rishabhpoddar, porcellus
Proposed by:

Context and Problem Statement#

When flattening the access token structure and making it into a standard JWT, we have to decide if it's safe to add all claims (including internally used ones) into the front-token, or not.

Considered Options#

  • Hide internal-only claims
  • Hide all claims not added by the user
  • Expose all claims

Decision Outcome#

We decided to expose all claims to the FE

  • Making them accessible to the FE is not a security risk
  • Straightforward interface

We can expose sub, exp and iat, because they have standard names and carry potentially useful information that we expose anyway. Exposing the sessionHandle should not cause any issues and could be useful in very rare cases on the frontend to detect session changes. This is only used on the CDI, while getting session information and updating sessionData in the database (not in access token). As a side-note, using the session handle to call updateSessionData doesn't seem to be documented. Exposing refreshTokenHash1, parentRefreshTokenHash1 to the frontend should not cause any issues, since they are never used as a part of the CDI or FDI. Only used in context of the (signed) access token.

Hide internal-only claims#

  • Hides claims that would be useless to the application
  • Exposes the standard claims (people have tried to get them through `getAccessTokenPayload` before)
  • Changes the current behaviour/interface (new props appearing in `getAccessTokenPayload`)
  • Hide all claims not added by the user#

  • Matches the current behaviour
  • Hides all claims that could be confusing
  • People have been looking for the userId claim
  • We are hiding otherwise standard claims
  • Expose all claims#

  • Front-token is very straght-forward
  • Changes the current behaviour/interface (new props appearing in `getAccessTokenPayload`)
  • Exposes the standard claims (people have tried to use them through getAccessTokenPayload before)
  • Could be confusing, but we can answer questions as they arise. We can decide to document this in the future if these questions get repeated too much.
  • `parentRefreshTokenHash1` and `refreshTokenHash1` are never used outside of the access token
  • Looking for older versions of the documentation?
    Which UI do you use?
    Custom UI
    Pre built UI