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.

After the access token becomes a full JWT, we can drop the backend-core handshake


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

rishabhpoddar, porcellus
Proposed by:

Context and Problem Statement#

The backend-core handshake is mainly used to fetch a few config values and the list of valid signing public keys we can use to locally validate access tokens. The fetched config values are:

  • Anti-csrf mode
  • Access token blacklisting enabled
  • Access token validity
  • Refresh token validity

Considered Options#

  • Keep the handshake
  • Remove handshake

Decision Outcome#

We can drop the handshake:

  • Anti-csrf mode can be defined on the backend
  • Access token blacklisting will be moved to the backend. This will be passed to the verify/getSession functions as checkDatabase: boolean
  • Validities are already sent in the create and refresh core API responses
  • The core JWKs endpoint can return the necessary public keys.
  • Since these JWTs (the access token) should still be signed in the Core, the validation should fetch the public keys from the Core as well, which should also conform to the standard. This implies that this route on the core should not expect the apiKey.
  • These public keys can be mirrored in the jwks endpoint exposed by the backend SDK if necessary (e.g.: other services/FE want to validate the JWT signature), but this can be disabled by the user if they want to.


  • This will enable us to use a standard JWT validation library to validate the access tokens
  • This should improve start-up times, which can be important in serverless environments
Looking for older versions of the documentation?
Which UI do you use?
Custom UI
Pre built UI