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.

Access token claims should be renamed to match JWT standards


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 tokens into a standard JWT. This means we will need to add some new claims, but some of them are already present with non-standard names.

Considered Options#

  • Duplicate claims
  • Rename claims

Decision Outcome#

We should rename claims to match the standard

  • We need to match the standard to enable our users to use a jwt verification library on backends without our SDKs.
  • We should not duplicate claims (if avoidable at all), because that would inflate the access token.

We will flatten the access token structure and add user claims to the root level instead of the old userData claim. Renamed claims:

  • userId -> sub
  • expiryTime -> exp (needs to be changed to be in seconds)
  • timeCreated -> iat (needs to be changed to be in seconds)

Unchanged claim names:

  • sessionHandle
  • refreshTokenHash1
  • parentRefreshTokenHash1
  • antiCsrfToken

We do not need to add:

  • aud: We could add a string to indicate it's a supertokens access token, but we'd not gain too much since we already do validation based on the object shape and we'd have to make this configurable anyway.
  • iss: although this is widely used, it's optional (as per the rfc) and we don't have meaningful information to put here.
  • nbf: this could contain timeCreated but since we do not issue tokens with nbf in the future this is not useful.
  • jti: since this has to be globally unique (even among JWTs), we do not have any id to store here.

While optional, we should add the kid (Key ID) Header Parameter

Which frontend SDK do you use?
supertokens-web-js / mobile