Docs

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
    strategy
    Type
    string
    Description

    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 address via Metamask. The web3_wallet_id parameter can also be specified to select which of the user's known Web3 wallets will be used.
    • web3_coinbase_wallet_signature: The verification will attempt to be completed using the user's Web3 wallet address via Coinbase Wallet. The web3_wallet_id parameter can also be specified to select which of the user's known Web3 wallets will be used.
    • web3_okx_wallet_signature: The verification will attempt to be completed using the user's Web3 wallet address via OKX Wallet. The web3_wallet_id parameter can also be specified to select which of the user's known Web3 wallets will be used.
    • oauth_<provider>: The user will be authenticated with their social sign-in account. See available social providers.
  • Name
    emailAddressId?
    Type
    string
    Description

    The ID 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.

  • Name
    phoneNumberId?
    Type
    string
    Description

    The ID 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.

  • Name
    web3WalletId?
    Type
    string
    Description

    The ID for the user's Web3 wallet address. This parameter will work only when the strategy is set to web3_metamask_signature, web3_coinbase_wallet_signature, or web3_okx_wallet_signature.

  • Name
    redirectUrl?
    Type
    string
    Description

    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>.

  • Name
    actionCompleteRedirectUrl?
    Type
    string
    Description

    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>.

Returns

TypeDescription
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
    strategy
    Type
    string
    Description

    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.
    • 'phone_code': User will receive a one-time code via SMS. At least one phone number should be on file for the user.
    • '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 address via Metamask.
    • 'web3_coinbase_wallet_signature': The verification will attempt to be completed using the user's Web3 wallet address via Coinbase Wallet.
    • 'web3_okx_wallet_signature': The verification will attempt to be completed using the user's Web3 wallet address via OKX Wallet.
    • 'passkey': The verification will attempt to be completed using the user's passkey.
    • 'reset_password_phone_code': Used when the user is trying to reset their password. The user will receive a one-time code via SMS.
    • 'reset_password_email_code': Used when the user is trying to reset their password. The user will receive a one-time code via email.
  • Name
    code?
    Type
    string
    Description

    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', 'phone_code', 'reset_password_phone_code', or 'reset_password_email_code'.

  • Name
    password?
    Type
    string
    Description

    The user's password string. This parameter is required only when strategy is set to password.

  • Name
    signature?
    Type
    string
    Description

    Web3 wallet generated signature to be verified. This parameter is required only for Web3 verification strategies.

Returns

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

Feedback

What did you think of this content?
Edit this page on GitHub

Last updated on