Skip to Content
Clerk logo

Clerk Docs

Ctrl + K
Go to clerk.com

First factor

These are all methods on the SignIn class that allow you to handle the first factor of a multi-factor authentication flow.

prepareFirstFactor()

function prepareFirstFactor(params: PrepareFirstFactorParams): Promise<SignIn>;

Begins the first factor verification process. This is a required step in order to complete a sign in, as users should be verified at least by one factor of authentication.

Common scenarios are one-time code (OTP) or social account (SSO) verification. This is determined by the accepted strategy parameter values. Each authentication identifier supports different strategies.

PrepareFirstFactorParams

NameTypeDescription
strategystringThe strategy value depends on the object's identifier value. Each authentication identifier supports different verification strategies. Possible strategy values are:
  • email_link: User will receive an email magic link via email. The email_address_id parameter can also be specified to select one of the user's known email addresses.
  • email_code: User will receive a one-time authentication code via email. At least one email address should be on file for the user. The email_address_id parameter can also be specified to select one of the user's known email addresses.
  • phone_code: User will receive a one-time authentication code in their phone, via SMS. At least one phone number should be on file for the user. The phone_number_id parameter can also be specified to select which of the user's known phone numbers the SMS will go to.
  • web3_metamask_signature: The verification will attempt to be completed using the user's web3 wallet public address. The web3_wallet_id parameter can also be specified to select which of the user's known web3 wallets will be used. Currently Clerk supports Metamask(opens in a new tab).
  • oauth_<provider>: The user will be authenticated with their social sign-in account. See available OAuth providers.
emailAddressId?stringUnique identifier for the user's email address that will receive an email message with the one-time authentication code. This parameter will work only when the email_code strategy is specified.
phoneNumberId?stringUnique identifier for the user's phone number that will receive an SMS message with the one-time authentication code. This parameter will work only when the phone_code strategy is specified.
web3WalletId?stringUnique identifier for the user's web3 wallet public address. This parameter will work only when the web3_metamask_signature strategy is specified.
redirectUrl?stringThe URL that the OAuth provider should redirect to, on successful authorization on their part. This parameter is required only if you set the strategy param to an OAuth strategy like oauth_<provider>.
actionCompleteRedirectUrl?stringThe URL that the user will be redirected to, after successful authorization from the OAuth provider and Clerk sign in. This parameter is required only if you set the strategy param to an OAuth strategy like oauth_<provider>.

Returns

TypeDescription
Promise<SignIn>This method returns a Promise which resolves with a SignIn object. Check the firstFactorVerification attribute for the status of the first factor verification process.

attemptFirstFactor()

function attemptFirstFactor(params: AttemptFirstFactorParams): Promise<SignIn>;

Attempts to complete the first factor verification process. This is a required step in order to complete a sign in, as users should be verified at least by one factor of authentication.

Make sure that a SignIn object already exists before you call this method, either by first calling SignIn.create or SignIn.prepareFirstFactor. The only strategy that does not require a verification to have already been prepared before attempting to complete it, is the password strategy.

Depending on the strategy that was selected when the verification was prepared, the method parameters should be different.

AttemptFirstFactorParams

NameTypeDescription
strategystringThe strategy value depends on the object's identifier value. Each authentication identifier supports different verification strategies. Possible strategy values are:
  • email_code: User will receive a one-time authentication code via email. At least one email address should be on file for the user. The email_address_id parameter can also be specified to select one of the user's known email addresses.
  • phone_code: User will receive a one-time authentication code in their phone, via SMS. At least one phone number should be on file for the user. The phone_number_id parameter can also be specified to select which of the user's known phone numbers the SMS will go to.
  • password: The verification will attempt to be completed with the user's password.
  • web3_metamask_signature: The verification will attempt to be completed using the user's web3 wallet public address. The web3_wallet_id parameter can also be specified to select which of the user's known web3 wallets will be used. Currently Clerk supports Metamask(opens in a new tab).
code?stringThe one-time code that was sent to the user as part of this verification step. This parameter is required only when strategy is set to email_code or phone_code.
password?stringThe user's password string. This parameter is required only when strategy is set to password.
signature?stringWeb3 wallet generated signature to be verified. This parameter is required only for web3 verification strategies.

Returns

TypeDescription
Promise<SignIn>This method returns a Promise which resolves with a SignIn object. Check the firstFactorVerification attribute for the status of the first factor verification process.

Last updated on March 19, 2024

What did you think of this content?

Clerk © 2024