Skip to main content
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.

Returns a SignIn object. Check the firstFactorVerification attribute for the status of the first factor verification process.

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

PrepareFirstFactorParams

  • Name
    strategy
    Type
    'email_link' | 'email_code' | 'phone_code' | 'web3_metamask_signature' | 'web3_coinbase_wallet_signature' | 'web3_okx_wallet_signature' | 'passkey' | 'oauth_<provider>' | 'enterprise_sso' | 'reset_password_phone_code' | 'reset_password_email_code'
    Description

    The strategy value depends on the SignIn.identifier value. Each authentication identifier supports different verification strategies. The following strategies are supported:

    • 'email_link': User will receive an email magic link via email.
    • 'email_code': User will receive a one-time authentication code via email. Requires emailAddressId parameter to be set.
    • 'phone_code': User will receive a one-time authentication code via SMS. Requires phoneNumberId parameter to be set.
    • 'web3_metamask_signature': The verification will attempt to be completed using the user's Web3 wallet address via Metamask. Requires web3WalletId parameter to be set.
    • 'web3_coinbase_wallet_signature': The verification will attempt to be completed using the user's Web3 wallet address via Coinbase Wallet. Requires web3WalletId parameter to be set.
    • 'web3_okx_wallet_signature': The verification will attempt to be completed using the user's Web3 wallet address via OKX Wallet. Requires web3WalletId parameter to be set.
    • 'passkey': The verification will attempt to be completed using the user's passkey.
    • 'oauth_<provider>': The user will be authenticated with their social connection account. See a list of supported values for <provider>.
    • 'saml' (deprecated): Deprecated in favor of 'enterprise_sso'. The user will be authenticated with their SAML account.
    • 'enterprise_sso': The user will be authenticated either through SAML or OIDC depending on the configuration of their enterprise SSO account.
    • 'reset_password_phone_code': Used when the user is trying to reset their password. The user will receive a one-time code via SMS. Requires phoneNumberId parameter to be set.
    • 'reset_password_email_code': Used when the user is trying to reset their password. The user will receive a one-time code via email. Requires emailAddressId parameter to be set.
  • Name
    emailAddressId?
    Type
    string
    Description

    Required if strategy is set to 'email_code' or 'reset_password_email_code'. The ID for the user's email address that will receive an email with the one-time authentication code.

  • Name
    phoneNumberId?
    Type
    string
    Description

    Required if strategy is set to 'phone_code' or 'reset_password_phone_code'. The ID for the user's phone number that will receive an SMS message with the one-time authentication code.

  • Name
    web3WalletId?
    Type
    string
    Description

    Required if strategy is set to 'web3_metamask_signature', 'web3_coinbase_wallet_signature', or 'web3_okx_wallet_signature'. The ID for the user's Web3 wallet address.

  • Name
    redirectUrl?
    Type
    string
    Description

    Required if strategy is set to 'oauth_<provider>' or 'enterprise_sso'. The full URL or path that the OAuth provider should redirect to after successful authorization on their part. Typically, this will be a simple /sso-callback route that either calls Clerk.handleRedirectCallback or mounts the <AuthenticateWithRedirectCallback /> component. See the custom flow for implementation details.

    Required if strategy is set to 'email_link'. The full URL that the user will be redirected to when they visit the email link. See the custom flow for implementation details.

  • Name
    actionCompleteRedirectUrl?
    Type
    string
    Description

    Required if strategy is set to 'oauth_<provider>' or 'enterprise_sso'. The URL that the user will be redirected to once the first factor verification is complete.

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.

Returns a SignIn object. Check the firstFactorVerification attribute for the status of the first factor verification process.

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

AttemptFirstFactorParams

  • Name
    strategy
    Type
    'email_code' | 'phone_code' | 'password' | 'web3_metamask_signature' | 'web3_coinbase_wallet_signature' | 'web3_okx_wallet_signature' | 'passkey' | 'reset_password_phone_code' | 'reset_password_email_code'
    Description

    The strategy value depends on the SignIn.identifier value. Each authentication identifier supports different verification strategies. The following strategies are supported:

    • '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

    Required if strategy is set to 'email_code', 'phone_code', 'reset_password_phone_code', or 'reset_password_email_code'. The one-time code that was sent to the user.

  • Name
    password?
    Type
    string
    Description

    Required if strategy is set to 'password'. The user's password string to be verified.

  • Name
    signature?
    Type
    string
    Description

    Required if strategy is set to web3_metamask_signature, web3_coinbase_wallet_signature, or web3_okx_wallet_signature. The Web3 wallet generated signature to be verified.

Feedback

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

Last updated on