Skip to main content
Docs

SignIn object (Legacy)

Warning

This page describes our legacy API, which will be removed in a future release. We recommend upgrading to Core 3 and using the SignInFuture object instead.

The SignIn object holds the state of the current sign-in and provides helper methods to navigate and complete the sign-in process. It is used to manage the sign-in lifecycle, including the first and second factor verification, and the creation of a new session.

The following steps outline the sign-in process:

  1. Initiate the sign-in process by collecting the user's authentication information and passing the appropriate parameters to the create() method.
  2. Prepare the by calling SignIn.prepareFirstFactor(). Users must complete a first factor verification. This can be something like providing a password, an email link, an , a Web3 wallet address, or providing proof of their identity through an external social account (SSO/OAuth).
  3. Attempt to complete the first factor verification by calling SignIn.attemptFirstFactor().
  4. Optionally, if you have enabled multi-factor (MFA) for your application, you will need to prepare the by calling SignIn.prepareSecondFactor().
  5. Attempt to complete the second factor verification by calling SignIn.attemptSecondFactor().
  6. If verification is successful, set the newly created session as the active session by passing the SignIn.createdSessionId to the setActive() method on the Clerk object. You may need to check for before the session can be set as active.

Example

See the custom flow guides for comprehensive examples of using the SignIn object to build custom user interfaces with the Clerk API.

Properties

  • Name
    id
    Type
    string | undefined
    Description

    The unique identifier for the sign-in attempt.

  • Name
    status
    Type
    SignInStatus | null
    Description

    The current status of the sign-in. SignInStatus supports the following values:

    • 'complete': The user is signed in and the can proceed to setActive() to create a session.
    • 'needs_identifier': The user's identifier (e.g., email address, phone number, username) hasn't been provided.
    • 'needs_first_factor': One of the following first factor verification strategies is missing: 'email_link', 'email_code', 'phone_code', 'web3_base_signature', 'web3_metamask_signature', 'web3_coinbase_wallet_signature', 'web3_okx_wallet_signature', 'web3_solana_signature', or 'oauth_provider'.
    • 'needs_second_factor': One of the following second factor verification strategies is missing: 'phone_code' or 'totp'.
    • 'needs_client_trust': The user is signing in from a new device and must complete a to establish Client Trust. See the Client Trust custom flow guide for more information.
    • 'needs_new_password': The user needs to set a new password.
  • Name
    supportedIdentifiers
    Type
    SignInIdentifier[]
    Description

    Array of all the authentication identifiers that are supported for this sign in. SignInIdentifier supports the following values:

    • 'email_address'
    • 'phone_number'
    • 'web3_wallet'
    • 'username'
  • Name
    identifier
    Type
    string | null
    Description

    Optional if the strategy is set to 'oauth_<provider>' or 'enterprise_sso'. Required otherwise. The authentication identifier value for the current sign-in.

  • Name
    supportedFirstFactors
    Type
    SignInFirstFactor[]
    Description

    Array of the that are supported in the current sign-in. Each factor contains information about the verification strategy that can be used. See the SignInFirstFactor type reference for more information.

  • Name
    supportedSecondFactors
    Type
    SignInSecondFactor[]
    Description

    Array of the that are supported in the current sign-in. Each factor contains information about the verification strategy that can be used. This property is populated only when the is verified. See the SignInSecondFactor type reference for more information.

  • Name
    firstFactorVerification
    Type
    VerificationResource
    Description

    The state of the verification process for the selected . Initially, this property contains an empty verification object, since there is no first factor selected. You need to call the prepareFirstFactor method in order to start the verification process.

  • Name
    secondFactorVerification
    Type
    VerificationResource
    Description

    The state of the verification process for the selected . Initially, this property contains an empty verification object, since there is no second factor selected. For the phone_code strategy, you need to call the prepareSecondFactor method in order to start the verification process. For the totp strategy, you can directly attempt the verification by calling the attemptSecondFactor method.

  • Name
    userData
    Type
    UserData
    Description

    An object containing information about the user of the current sign-in. This property is populated only once an identifier is given to the SignIn object.

  • Name
    createdSessionId
    Type
    string | null
    Description

    The identifier of the session that was created upon completion of the current sign-in. The value of this property is null if the sign-in status is not 'complete'.

  • Name
    clientTrustState
    Type
    ClientTrustState | undefined
    Description

    The Client Trust state for the sign-in when the user is signing in from a new device. Populated when the sign-in requires establishing client trust (e.g. status is 'needs_client_trust').

Methods

attemptFirstFactor()

Attempts to complete the 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 will be different.

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

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

AttemptFirstFactorParams

  • Name
    strategy
    Type
    'email_code' | 'phone_code' | 'password' | 'web3_base_signature' | 'web3_metamask_signature' | 'web3_coinbase_wallet_signature' | 'web3_okx_wallet_signature' | 'web3_solana_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 an via email. At least one email address should be on file for the user.
    • 'phone_code': User will receive an 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_base_signature': The verification will attempt to be completed using the user's Web3 wallet address via Base.
    • '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.
    • 'web3_solana_signature': The verification will attempt to be completed using the user's Web3 wallet address via their Solana wallet provider.
    • '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 an via SMS.
    • 'reset_password_email_code': Used when the user is trying to reset their password. The user will receive an 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 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_base_signature', 'web3_metamask_signature', 'web3_coinbase_wallet_signature', 'web3_okx_wallet_signature', or 'web3_solana_signature'. The Web3 wallet generated signature to be verified.

attemptSecondFactor()

Attempts to complete the process, also known as multi-factor authentication (MFA).

Note

For the phone_code strategy, make sure that a verification has already been prepared before you call this method, by first calling SignIn.prepareSecondFactor.

Returns a SignIn object. Check the secondFactorVerification attribute for the status of the second factor verification process.

function attemptSecondFactor(params: AttemptSecondFactorParams): Promise<SignIn>

AttemptSecondFactorParams

  • Name
    strategy
    Type
    'phone_code' | 'totp'
    Description

    The strategy to be used for . Possible strategy values are

    • 'phone_code': User will receive an via SMS. At least one phone number should be on file for the user.
    • 'totp': User must provide a 6-digit TOTP code generated by their authenticator app. The user must have previously created a TOTP secret and registered it in their authenticator app using a QR code, URI, or by manually entering the secret.
  • Name
    code
    Type
    string
    Description
    • For the 'phone_code' strategy: The that was sent to the user as part of the prepareSecondFactor() step.
    • For the 'totp' strategy: The TOTP generated by the user's authenticator app.

authenticateWithBase()

Initiates an authentication flow using Base, allowing users to authenticate via their Web3 wallet address. This method prompts the user to connect their Base account and sign a message to verify ownership of the wallet address.

function authenticateWithBase(): Promise<SignInResource>

authenticateWithCoinbaseWallet()

Initiates an authentication flow using the Coinbase Wallet browser extension, allowing users to authenticate via their Web3 wallet address. This method prompts the user to connect their Coinbase Wallet and sign a message to verify ownership of the wallet address.

function authenticateWithCoinbaseWallet(): Promise<SignInResource>

authenticateWithMetamask()

Initiates an authentication flow using the MetaMask browser extension, allowing users to authenticate via their Ethereum wallet address. This method prompts the user to connect their MetaMask wallet and sign a message to verify ownership of the wallet address.

function authenticateWithMetamask(): Promise<SignInResource>

authenticateWithOKXWallet()

Initiates an authentication flow using the OKX Wallet browser extension, allowing users to authenticate via their Web3 wallet address. This method prompts the user to connect their OKX Wallet and sign a message to verify ownership of the wallet address.

function authenticateWithOKXWallet(): Promise<SignInResource>

authenticateWithSolana()

Initiates an authentication flow using the user's Solana wallet provider, allowing users to authenticate via their Solana wallet address. This method prompts the user to connect their Solana wallet and sign a message to verify ownership of the wallet address. The walletName parameter specifies which Solana wallet provider to use for the authentication process, which is required to initiate the connection and signature request.

function authenticateWithSolana(params: SignInAuthenticateWithSolanaParams): Promise<SignInResource>

SignInAuthenticateWithSolanaParams

  • Name
    walletName
    Type
    string
    Description

    The name of the Solana wallet provider to use for the authentication process.

authenticateWithPasskey()

Initiates a passkey-based authentication flow, enabling users to authenticate using a previously registered passkey. When called without parameters, this method requires a prior call to SignIn.create({ strategy: 'passkey' }) to initialize the sign-in context. This pattern is particularly useful in scenarios where the authentication strategy needs to be determined dynamically at runtime.

function authenticateWithPasskey(params?: AuthenticateWithPasskeyParams): Promise<SignInResource>
AuthenticateWithPasskeyParams
  • Name
    flow
    Type
    'autofill' | 'discoverable'
    Description

    The flow to use for the passkey sign-in.

    • 'autofill': The client prompts your users to select a passkey before they interact with your app.
    • 'discoverable': The client requires the user to interact with the client.

authenticateWithRedirect()

Signs in a user via a Single Sign On (SSO) connection, such as OAuth or SAML, where an external account is used for verifying the user's identity.

function authenticateWithRedirect(params: AuthenticateWithRedirectParams): Promise<void>

AuthenticateWithRedirectParams

  • Name
    strategy
    Type
    OAuthStrategy | 'enterprise_sso'
    Description

    The strategy to use for authentication. The following strategies are supported:

  • Name
    redirectUrl
    Type
    string
    Description

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

  • Name
    redirectUrlComplete
    Type
    string
    Description

    The full URL or path that the user will be redirected to once the sign-in is complete.

  • Name
    continueSignUp?
    Type
    boolean | undefined
    Description

    Whether to continue (i.e. PATCH) an existing SignUp (if present) or create a new SignUp.

  • Name
    continueSignIn?
    Type
    boolean | undefined
    Description

    Whether to continue (i.e. PATCH) an existing SignIn (if present) or create a new SignIn.

  • Name
    identifier?
    Type
    string | undefined
    Description

    The ID used to target an enterprise connection during sign-in.

  • Name
    emailAddress?
    Type
    string | undefined
    Description

    The email address used to target an enterprise connection during sign-in.

  • Name
    legalAccepted?
    Type
    boolean | undefined
    Description

    Indicates whether the user has agreed to the legal compliance documents.

  • Name
    oidcPrompt?
    Type
    string
    Description

    The value to pass to the OIDC prompt parameter in the generated OAuth redirect URL.

  • Name
    enterpriseConnectionId?
    Type
    string
    Description

    Optional if the strategy is set to enterprise_sso. The identifier of the enterprise connection to target during sign-in. This is required if there are multiple enterprise connections configured in the instance.

authenticateWithPopup()

Opens a popup window to allow a user to sign in via a Single Sign On (SSO) connection, such as OAuth or SAML, where an external account is used for verifying the user's identity.

function authenticateWithPopup(params: AuthenticateWithPopupParams): Promise<void>

AuthenticateWithPopupParams

  • Name
    redirectUrl
    Type
    string
    Description

    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.

  • Name
    redirectUrlComplete
    Type
    string
    Description

    The full URL or path to navigate to after the OAuth or SAML flow completes.

  • Name
    strategy
    Type
    OAuthStrategy | 'enterprise_sso'
    Description

    The strategy to use for authentication. The following strategies are supported:

  • Name
    popup
    Type
    Window
    Description

    A reference to a popup window opened via window.open().

  • Name
    continueSignUp?
    Type
    boolean | undefined
    Description

    Whether to continue (i.e. PATCH) an existing SignUp (if present) or create a new SignUp.

  • Name
    continueSignIn?
    Type
    boolean | undefined
    Description

    Whether to continue (i.e. PATCH) an existing SignIn (if present) or create a new SignIn.

  • Name
    emailAddress?
    Type
    string | undefined
    Description

    Email address to use for targeting an enterprise connection at sign-up.

  • Name
    identifier?
    Type
    string | undefined
    Description

    Identifier to use for targeting an enterprise connection at sign-up.

  • Name
    legalAccepted?
    Type
    boolean
    Description

    A boolean indicating whether the user has agreed to the legal compliance documents.

  • Name
    unsafeMetadata?
    Type
    SignUpUnsafeMetadata
    Description

    Metadata that can be read and set from the frontend. Once the sign-up is complete, the value of this field will be automatically copied to the newly created user's unsafe metadata. One common use case for this attribute is to use it to implement custom fields that can be collected during sign-up and will automatically be attached to the created User object.

  • Name
    oidcPrompt?
    Type
    string
    Description

    The value to pass to the OIDC prompt parameter in the generated OAuth redirect URL.

  • Name
    enterpriseConnectionId?
    Type
    string
    Description

    Optional if the strategy is set to enterprise_sso. The identifier of the enterprise connection to target during sign-up. This is required if there are multiple enterprise connections configured in the instance.

authenticateWithWeb3()

Initiates a Web3 authentication flow by verifying the user's ownership of a blockchain wallet address through cryptographic signature verification. This method enables decentralized authentication without requiring traditional credentials.

Note

When the strategy is web3_solana_signature, the walletName parameter must be specified to indicate which Solana wallet provider to use for the authentication process.

function authenticateWithWeb3(params: AuthenticateWithWeb3Params): Promise<SignInResource>

AuthenticateWithWeb3Params

  • Name
    identifier
    Type
    string
    Description

    The user's Web3 ID.

  • Name
    generateSignature
    Type
    (opts: GenerateSignatureParams) => Promise<string>
    Description

    The method of how to generate the signature for the Web3 sign-in. See GenerateSignatureParams for more information.

  • Name
    strategy?
    Type
    Web3Strategy
    Description

    The Web3 verification strategy.

  • Name
    walletName?
    Type
    string
    Description

    The name of the wallet provider to use for the authentication process. This parameter is required when using web3_solana_signature as the strategy.

GenerateSignatureParams
  • Name
    identifier
    Type
    string
    Description

    The user's Web3 wallet address.

  • Name
    nonce
    Type
    string
    Description

    The cryptographic nonce used in the sign-in.

  • Name
    provider?
    Type
    Web3Provider
    Description

    The Web3 provider to generate the signature with. See Web3Provider for more information.

  • Name
    walletName?
    Type
    string
    Description

    The name of the wallet provider to use for the authentication process. This parameter is required when using solana as the provider.

create()

Creates and returns a new SignIn instance initialized with the provided parameters. The instance maintains the sign-in lifecycle state through its status property, which updates as the authentication flow progresses. This method serves as the entry point for initiating a sign-in flow.

What you must pass to params depends on which sign-in options you have enabled in your app's settings in the Clerk Dashboard.

You can complete the sign-in process in one step if you supply the required fields to create(). Otherwise, Clerk's sign-in process provides great flexibility and allows users to easily create multi-step sign-in flows.

Warning

Once the sign-in process is complete, pass the createdSessionId to the setActive() method on the Clerk object. This will set the newly created session as the active session.

function create(params: SignInCreateParams): Promise<SignIn>

SignInCreateParams

  • Name
    strategy?
    Type
    'password' | 'email_link' | 'email_code' | 'phone_code' | OAuthStrategy | 'enterprise_sso' | 'passkey' | 'web3_base_signature' | 'web3_metamask_signature' | 'web3_coinbase_wallet_signature' | 'web3_okx_wallet_signature' | 'web3_solana_signature' | 'ticket' | 'google_one_tap'
    Description

    The strategy to use in the sign-in flow. Depends on the SignIn.identifier value. Each authentication identifier supports different verification strategies. The following strategies are supported:

    • 'password': The verification will attempt to be completed using the user's password.

    • 'email_link': User will receive an email magic link via email. The identifier parameter can also be specified to select one of the user's known email addresses. The redirectUrl parameter can also be specified.

    • 'email_code': User will receive an via email. The identifier parameter can also be specified to select one of the user's known email addresses.

    • 'phone_code': User will receive an via SMS. The identifier parameter can also be specified to select one of the user's known phone numbers.

    • 'oauth_<provider>': The user will be authenticated with their social connection account. See a list of supported values for <provider>.

    • 'enterprise_sso': The user will be authenticated either through SAML or OIDC depending on the configuration of their enterprise SSO account.

    • 'passkey': The user will be authenticated with their passkey.

    • 'web3_base_signature': The verification will attempt to be completed using the user's Web3 wallet address via Base. The identifier parameter can also be specified to select which of the user's known Web3 wallets will be used.

    • 'web3_metamask_signature': The verification will attempt to be completed using the user's Web3 wallet address via Metamask. The identifier 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 identifier 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 identifier parameter can also be specified to select which of the user's known Web3 wallets will be used.

    • 'web3_solana_signature': The verification will attempt to be completed using the user's Web3 wallet address via their Solana wallet provider. The identifier parameter can also be specified to select which of the user's known Web3 wallets will be used.

    • 'ticket': The user will be authenticated via the ticket or token generated from the Backend API.

    • 'google_one_tap': The user will be authenticated with the Google One Tap UI. It's recommended to use authenticateWithGoogleOneTap() instead, as it will also set the user's current session as active for you.

  • Name
    identifier
    Type
    string
    Description

    The authentication identifier for the sign-in. This can be the value of the user's email address, phone number, username, or Web3 wallet address.

  • Name
    password?
    Type
    string
    Description

    The user's password. Only supported if strategy is set to 'password' and Password is enabled.

  • Name
    ticket?
    Type
    string
    Description

    Required if strategy is set to 'ticket'. The ticket or token generated from the Backend API.

  • Name
    redirectUrl?
    Type
    string
    Description

    If strategy is set to 'oauth_<provider>' or 'enterprise_sso', this specifies 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.

    If strategy is set to 'email_link', this specifies the 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

    Optional if strategy is set to 'oauth_<provider>' or 'enterprise_sso'. The URL that the user will be redirected to, after successful authorization from the OAuth provider and Clerk sign-in.

  • Name
    transfer?
    Type
    boolean
    Description

    When set to true, the SignIn will attempt to retrieve information from the active SignUp instance and use it to complete the sign-in process. This is useful when you want to seamlessly transition a user from a sign-up attempt to a sign-in attempt.

  • Name
    oidcPrompt?
    Type
    string
    Description

    Optional if strategy is set to 'oauth_<provider>' or 'enterprise_sso'. The value to pass to the OIDC prompt parameter in the generated OAuth redirect URL.

  • Name
    oidcLoginHint?
    Type
    string
    Description

    Optional if strategy is set to 'oauth_<provider>' or 'enterprise_sso'. The value to pass to the OIDC login_hint parameter in the generated OAuth redirect URL.

Creates a flow for authenticating users via email links. This method returns functions for initiating and canceling the email link verification process; see the returns section for more information.

function createEmailLinkFlow(): {
  startEmailLinkFlow: (params: SignInStartEmailLinkFlowParams) => Promise<SignIn>
  cancelEmailLinkFlow: () => void
}

Returns

createEmailLinkFlow returns an object with two functions:

  • Name
    startEmailLinkFlow
    Type
    (params: SignInStartEmailLinkFlowParams) => Promise<SignIn>
    Description

    Function to start the email link flow. It prepares an email link verification and polls for the verification result.

  • Name
    cancelEmailLinkFlow
    Type
    () => void
    Description

    Function to cleanup the email link flow. Stops waiting for verification results.

  • Name
    emailAddressId
    Type
    string
    Description

    The ID of the user's email address that's going to be used as the first factor identification for verification.

  • Name
    redirectUrl
    Type
    string
    Description

    The full URL that the user will be redirected to when they visit the email link.

prepareFirstFactor()

Begins the 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 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_base_signature' | 'web3_metamask_signature' | 'web3_coinbase_wallet_signature' | 'web3_okx_wallet_signature' | 'web3_solana_signature' | 'passkey' | OAuthStrategy | '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 an via email. Requires emailAddressId parameter to be set.
    • 'phone_code': User will receive an via SMS. Requires phoneNumberId parameter to be set.
    • 'web3_base_signature': The verification will attempt to be completed using the user's Web3 wallet address via Base. Requires web3WalletId 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.
    • 'web3_solana_signature': The verification will attempt to be completed using the user's Web3 wallet address via their Solana wallet provider. Requires web3WalletId parameter to be set.
    • 'passkey': The verification will attempt to be completed using the user's passkey.
    • OAuthStrategy: The user will be authenticated with their social connection 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 an 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 an 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 .

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

  • Name
    default?
    Type
    boolean
    Description

    Optional if strategy is set to 'phone_code'. Whether this phone number is the default for the strategy.

  • Name
    channel?
    Type
    string
    Description

    Optional if strategy is set to 'phone_code'. The channel to use for sending the OTP (e.g. 'sms').

  • Name
    web3WalletId?
    Type
    string
    Description

    Required if strategy is set to 'web3_base_signature', 'web3_metamask_signature', 'web3_coinbase_wallet_signature', 'web3_okx_wallet_signature', or 'web3_solana_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.

prepareSecondFactor()

Begins the process, also known as multi-factor authentication (MFA).

Note

If the strategy was set to totp (e.g. SignIn.create({ strategy: 'totp' })), it does not require preparation. You can directly attempt the second factor verification by calling SignIn.attemptSecondFactor.

Returns a SignIn object. Check the secondFactorVerification attribute for the status of the second factor verification process.

function prepareSecondFactor(params: PrepareSecondFactorParams): Promise<SignIn>

PrepareSecondFactorParams

  • Name
    strategy
    Type
    'phone_code'
    Description

    The strategy used for . Supported strategies are:

    • 'phone_code': User will receive an via SMS. At least one phone number should be on file for the user.
  • Name
    phoneNumberId
    Type
    string
    Description

    The ID for the user's phone number that will receive an SMS message with the .

resetPassword()

Resets a user's password. It's recommended to use the custom flow for resetting a user's password instead.

function resetPassword(params: ResetPasswordParams): Promise<SignIn>

ResetPasswordParams

  • Name
    password
    Type
    string
    Description

    The user's new password.

  • Name
    signOutOfOtherSessions?
    Type
    boolean | undefined
    Description

    If true, signs the user out of all other authenticated sessions.

validatePassword()

Validates a password against the instance's password policy (e.g. minimum length, complexity). Uses the same rules as the Clerk Dashboard configuration. Useful for client-side validation before submitting a sign-up or password reset. Accepts a callback that receives validation errors.

function validatePassword(
  password: string,
  callback?: (errors: string[]) => void,
): boolean | undefined

Feedback

What did you think of this content?

Last updated on

GitHubEdit on GitHub