Which UI do you use?

Custom UI

Pre built UI

User Creation

Email Password Migration

important

If you do not have access to your user's password hashes, you can use our guide for migrating them dynamically during login.

SuperTokens allows you to import users with password hashes generated with BCrypt, Argon2 and Firebase SCrypt with our import user API. You can find the API spec here.

Migrating users With Argon2 or BCrypt Password hashes

For users with BCrypt or Argon2 password hashes you can use the following curl command to import your user.

Single tenant / app setup

curl --location --request POST '/recipe/user/passwordhash/import' \
--header 'api-key: ' \
--header 'Content-Type: application/json; charset=utf-8' \
--data-raw '{
    "email": "johndoe@example.com",
    "passwordHash": "$argon2d$v=19$m=12,t=3,p=1$NWd0eGp4ZW91b3IwMDAwMA$57jcfXF19MyiUXSjkVBpEQ"
}'

important

SuperTokens accepts BCrypt and Argon2 hashes in standard format. When exporting password hashes from authentication providers the structure might be changed. For example, Auth0 prepends an identifier to the exported password hashes which needs to removed before importing into SuperTokens.

Sample password hashes for BCrypt and Argon2 in standard format:

• BCrypt: $2a$10$GzEm3vKoAqnJCTWesRARCe/ovjt/07qjvcH9jbLUg44Fn77gMZkmm
• Argon2: $argon2id$v=19$m=16,t=2,p=1$VG1Oa1lMbzZLbzk5azQ2Qg$kjcNNtZ/b0t/8HgXUiQ76A

Multi tenant / app setup

curl --location --request POST '/recipe/user/passwordhash/import' \
--header 'api-key: ' \
--header 'Content-Type: application/json; charset=utf-8' \
--data-raw '{
    "email": "johndoe@example.com",
    "passwordHash": "$argon2d$v=19$m=12,t=3,p=1$NWd0eGp4ZW91b3IwMDAwMA$57jcfXF19MyiUXSjkVBpEQ"
}'

important

SuperTokens accepts BCrypt and Argon2 hashes in standard format. When exporting password hashes from authentication providers the structure might be changed. For example, Auth0 prepends an identifier to the exported password hashes which needs to removed before importing into SuperTokens.

Sample password hashes for BCrypt and Argon2 in standard format:

• BCrypt: $2a$10$GzEm3vKoAqnJCTWesRARCe/ovjt/07qjvcH9jbLUg44Fn77gMZkmm
• Argon2: $argon2id$v=19$m=16,t=2,p=1$VG1Oa1lMbzZLbzk5azQ2Qg$kjcNNtZ/b0t/8HgXUiQ76A

Migrating users with Firebase SCrypt Password hashes

Importing users from Firebases requires an update to your supertokens core config and formatting the input password hash.

Step 1: Retrive your Firebase password hashing parameters from your dashboard.

Step 2: Update the SuperTokens core to use the base64_signer_key

Managed service

• Edit the core configuration in the SuperTokens Managed Service Dashboard.
• Set the firebase_password_hashing_signer_key field in the config to the base64_signer_key retrieved from your firebase hashing parameters.

Self hosted

With Docker

 docker run \
    -p 3567:3567 \
    -e FIREBASE_PASSWORD_HASHING_SIGNER_KEY="gRhC3eDeQOdyEn4bMd9c6kxguWVmcIVq/HbJKnCXdWscZx0l2WbCJ1wbg==" \ 
    -d registry.supertokens.io/supertokens/supertokens-<db_name>

Without Docker

# Add your base64_signer_key to the following in the config.yaml file.
# The file path can be found by running the "supertokens --help" command

firebase_password_hashing_signer_key: "gRhC3eDeQOdyEn4bMd9c6kxguWVmcIVq/HbJKnCXdWscZx0l2WbCJ1wbg=="

Step 3: SuperTokens requires firebase password hashes to be in a specific format to be parsed.

For example:

Your exported firebase user has the following credentials:

{
  "users": [
    {
      "localId": "userId",
      "email": "johnDoe@example.com"
      "passwordHash": "9Y8ICWcqbzmI42DxV1jpyEjbrJPG8EQ6nI6oC32JYz+/dd7aEjI/R7jG9P5kYh8v9gyqFKaXMDzMg7eLCypbOA==",
      "salt": "/cj0jC1br5o4+w==",
    }
  ]
}

The memory cost, rounds and salt separator retrived from the password hashing config are:

{
  mem_cost: 14,
  rounds: 8,
  base64_salt_separator: "Bw=="
}

The password hash would be the following: $f_scrypt$9Y8ICWcqbzmI42DxV1jpyEjbrJPG8EQ6nI6oC32JYz+/dd7aEjI/R7jG9P5kYh8v9gyqFKaXMDzMg7eLCypbOA==$/cj0jC1br5o4+w==$m=14$r=8$s=Bw==

The example password hash is in the following format $f_scrypt$<passwordHash>$<salt>$m=<mem_cost>$r=<rounds>$s=<base64_salt_separator>

Step 4: Run the following curl command to import the user

Single tenant / app setup

curl --location --request POST '/recipe/user/passwordhash/import' \
--header 'Content-Type: application/json; charset=utf-8' \
--header 'api-key: ' \
--data-raw '{
  "email": "test@example.com",
  "passwordHash": "$f_scrypt$9Y8ICWcqbzmI42DxV1jpyEjbrJPG8EQ6nI6oC32JYz+/dd7aEjI/R7jG9P5kYh8v9gyqFKaXMDzMg7eLCypbOA==$/cj0jC1br5o4+w==$m=14$r=8$s=Bw==",
  "hashingAlgorithm": "firebase_scrypt"
}'

Multi tenant / app setup

curl --location --request POST '/recipe/user/passwordhash/import' \
--header 'Content-Type: application/json; charset=utf-8' \
--header 'api-key: ' \
--data-raw '{
  "email": "test@example.com",
  "passwordHash": "$f_scrypt$9Y8ICWcqbzmI42DxV1jpyEjbrJPG8EQ6nI6oC32JYz+/dd7aEjI/R7jG9P5kYh8v9gyqFKaXMDzMg7eLCypbOA==$/cj0jC1br5o4+w==$m=14$r=8$s=Bw==",
  "hashingAlgorithm": "firebase_scrypt"
}'