Time-based One-time Password (TOTP)
Clerk supports multi-factor authentication (MFA) using Time-based One-time Password (TOTP) as a second factor. TOTP is a widely used standard for generating one-time passwords that are valid for a short period of time.
These methods on the User
object are related to TOTP functionality and allow you to generate and verify TOTP secrets, disable TOTP, and create backup codes for user authentication.
To see how all these methods work together, see the comprehensive example.
createTOTP()
Generates a TOTP secret for a user that can be used to register the application on the user's authenticator app of choice. Note that if this method is called again (while still unverified), it replaces the previously generated secret.
verifyTOTP()
Verifies a TOTP secret after a user has created it. The user must provide a code from their authenticator app that has been generated using the previously created secret. This way, correct set up and ownership of the authenticator app can be validated.
- Name
code
- Type
string
- Description
A 6 digit TOTP generated from the user's authenticator app.
disableTOTP()
Disables TOTP by deleting the user's TOTP secret.
createBackupCode()
Generates a fresh new set of backup codes for the user.
Every time the method is called, it will replace the previously generated backup codes.
Can only be created for the user if the user has another multi-factor authentication method enabled for their account, as backup codes are a fallback for when the user is unable to use their primary MFA method.
- Name
id
- Type
string
- Description
The unique identifier for this TOTP secret.
- Name
secret?
- Type
string
- Description
The generated TOTP secret. Note: this is only returned to the client upon creation and cannot be retrieved afterwards.
- Name
uri?
- Type
string
- Description
A complete TOTP configuration URI including the Issuer, Account, etc that can be pasted to an authenticator app or encoded to a QR code and scanned for convenience. Just like the secret, the URI is exposed to the client only upon creation and cannot be retrieved afterwards.
- Name
verified
- Type
boolean
- Description
Whether this TOTP secret has been verified by the user by providing one code generated with it. TOTP is not enabled on the user unless they have a verified secret.
- Name
backupCodes?
- Type
string[]
- Description
A set of fresh generated Backup codes. Note that this will be populated if the feature is enabled in your instance and the user doesn't already have backup codes generated.
- Name
createdAt
- Type
Date
- Description
The date when the TOTP secret was created.
- Name
updatedAt
- Type
Date
- Description
The date when the TOTP secret was last updated.
- Name
id
- Type
string
- Description
The unique identifier for this TOTP secret.
- Name
codes
- Type
string[]
- Description
The generated set of backup codes.
- Name
createdAt
- Type
Date
- Description
The date when the backup codes were created.
- Name
updatedAt
- Type
Date
- Description
The date when the backup codes were last updated.
TOTP example
The following example demonstrates how to use the TOTP methods to create and verify a TOTP secret, disable TOTP, and create backup codes for a user. To ease the development process, the response or error message of a method will be displayed on the user interface.
The following example assumes:
-
you have followed the quickstart in order to add Clerk to your JavaScript application
-
you have enabled authenticator application and backup codes as multi-factor strategies in the Clerk Dashboard
Feedback
Last updated on