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()`

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.


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

`PrepareFirstFactorParams`

Name	Type	Description
`strategy`	`string`	The `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?`	`string`	Unique 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?`	`string`	Unique 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?`	`string`	Unique identifier for the user's web3 wallet public address. This parameter will work only when the `web3_metamask_signature` strategy is specified.
`redirectUrl?`	`string`	The 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?`	`string`	The 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>`.

`prepareFirstFactor()` returns

Type	Description
`Promise<SignIn>`	A `Promise` which resolves with a `SignIn` object. Check the `firstFactorVerification` attribute for the status of the first factor verification process.

`attemptFirstFactor()`

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.


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

`AttemptFirstFactorParams`

Name	Type	Description
`strategy`	`string`	The `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?`	`string`	The 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?`	`string`	The user's password string. This parameter is required only when `strategy` is set to `password`.
`signature?`	`string`	Web3 wallet generated signature to be verified. This parameter is required only for web3 verification strategies.

`attemptFirstFactor()` returns

Type	Description
`Promise<SignIn>`	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

prepareFirstFactor()

PrepareFirstFactorParams

prepareFirstFactor() returns

attemptFirstFactor()

AttemptFirstFactorParams