Skip to main content

If you are using our backend SDK that is lesser than the following versions, please visit the older documentation link here.

Password Hashing

SuperTokens supports two password hashing algorithms:

  • BCrypt (default)
  • Argon2id (available only for core version >= 3.12)

Interoperable#

You can switch algorithms whenever needed. Existing passwords that use an algorithm will continue to use that algorithm for verification even if the other algorithm is configured.

For example, if a password was originally hashed with BCrypt, it will be verified using BCrypt even if the core's setting is Argon2. The setting only affects which algorithm to use for new passwords.

Time taken for hashes#

The key metric to aim for when hashing passwords is the amount of time each hash would take. By default, SuperTokens has configured these algorithms to take 300 milliseconds per hash on a machine with 1 GB of RAM and 2 virtual CPU cores.

Recommended algorithm#

As per current best practices, Argon2id is the recommended algorithm to use for password hashing. However, we have chosen BCrypt by default because using Argon2 requires to give it settings that are specific to the hardware that the core is running on.

important

We recommend that you using Argon2 hashing if possible.

Calibration CLI tool#

note

This is only applicable if you are self hosting SuperTokens. For our managed service, we have already calibrated the algorithms based on the hardware we use.

We also provide a CLI command to calibrate the password hashing algorithm (for core version >= v3.12):

docker run registry.supertokens.io/supertokens/supertokens-<db_name> supertokens hashingCalibrate --help
Looking for older versions of the documentation?
Which UI do you use?
Custom UI
Pre built UI