Skip to main content
Docs

SignInFuture

Important

The APIs described here are stable, and will become the default in the next major version of clerk-js.

The SignInFuture class 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.

Properties

  • Name
    createdSessionId
    Type
    null | string
    Description

    The ID 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
    existingSession?
    Type
    { sessionId: string }
    Description

    If present, reflects that the sign-in was not able to create a new session because the identifier already exists in an existing session. Contains the ID of the existing session.

  • Name
    firstFactorVerification
    Type
    VerificationResource
    Description

    The state of the verification process for the selected first factor. Initially, this property contains an empty verification object, since there is no first factor selected.

  • Name
    id?
    Type
    string
    Description

    The unique identifier for the current sign-in attempt.

  • Name
    identifier
    Type
    null | string
    Description

    The authentication identifier value for the current sign-in. null if the strategy is 'oauth_<provider>' or 'enterprise_sso'.

  • Name
    isTransferable
    Type
    boolean
    Description

    Indicates that there is not a matching user for the first-factor verification used, and that the sign-in can be transferred to a sign-up.

  • Name
    secondFactorVerification
    Type
    VerificationResource
    Description

    The state of the verification process for the selected second factor. Initially, this property contains an empty verification object, since there is no second factor selected.

  • Name
    status
    Type
    SignInStatus
    Description

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

    • 'complete': The user is signed in and the can proceed to finalize() to set the newly created session as the active 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 strategies is missing: 'email_link', 'email_code', passkey, password, 'phone_code', 'web3_base_signature', 'web3_metamask_signature', 'web3_coinbase_wallet_signature', 'web3_okx_wallet_signature', 'web3_solana_signature', OAuthStrategy, or 'enterprise_sso'.
    • 'needs_second_factor': One of the following strategies is missing: 'phone_code', 'totp', 'backup_code', 'email_code', or 'email_link'.
    • 'needs_new_password': The user needs to set a new password. See the dedicated custom flow guide for more information.
  • Name
    supportedFirstFactors
    Type
    SignInFirstFactor[]
    Description

    Array of the first factors that are supported in the current sign-in. Each factor contains information about the verification strategy that can be used.

  • Name
    supportedSecondFactors
    Type
    SignInSecondFactor[]
    Description

    Array of the second factors 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 first factor is verified.

  • 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 through signIn.create() or another method that populates the identifier property.

Methods

create()

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

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

Important

The signIn.create() method is intended for advanced use cases. For most use cases, prefer the use of the factor-specific methods such as signIn.password(), signIn.emailCode.sendCode(), etc.

Warning

Once the sign-in process is complete, call the signIn.finalize() method to set the newly created session as the active session.

function create(params: SignInFutureCreateParams): Promise<{ error: ClerkError | null }>

SignInFutureCreateParams

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

  • 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
    redirectUrl?
    Type
    string
    Description

    The full URL or path that the OAuth provider should redirect to after successful authorization on their part.

  • Name
    strategy?
    Type
    OAuthStrategy | "enterprise_sso" | "passkey"
    Description

    The first factor verification strategy to use in the sign-in flow. Depends on the identifier value. Each authentication identifier supports different verification strategies.

  • Name
    ticket?
    Type
    string
    Description

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

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

emailCode.sendCode()

Sends an email code to sign in with.

function sendCode(params: SignInFutureEmailCodeSendParams): Promise<{ error: ClerkError | null }>

SignInFutureEmailCodeSendParams

  • Name
    emailAddress?
    Type
    string
    Description

    The user's email address.

  • Name
    emailAddressId?
    Type
    string
    Description

    The ID for the user's email address that will receive an email with the one-time authentication code.

emailCode.verifyCode()

Verifies an email code sent with the emailCode.sendCode() method.

function verifyCode(
  params: SignInFutureEmailCodeVerifyParams,
): Promise<{ error: ClerkError | null }>

SignInFutureEmailCodeVerifyParams

  • Name
    code
    Type
    string
    Description

    The one-time code that was sent to the user as part of the signIn.emailCode.sendCode() method.

Sends an email link to sign in with.

function sendLink(params: SignInFutureEmailLinkSendParams): Promise<{ error: ClerkError | null }>
  • Name
    verificationUrl
    Type
    string
    Description

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

The verification status of the email link. This property is populated by reading query parameters from the URL after the user visits the email link. Returns null if no verification status is available.

  • Name
    status
    Type
    'verified' | 'expired' | 'failed' | 'client_mismatch'
    Description

    The verification status.

  • Name
    createdSessionId
    Type
    string
    Description

    The ID of the session that was created upon successful verification.

  • Name
    verifiedFromTheSameClient
    Type
    boolean
    Description

    Whether the verification was completed from the same client (browser) that initiated the email link flow.

Waits for email link verification to complete or expire.

function waitForVerification(): Promise<{ error: ClerkError | null }>

finalize()

Converts a sign-in with status === 'complete' into an active session. Will cause anything observing the session state (such as the useUser() hook) to update automatically.

function finalize(params?: SignInFutureFinalizeParams): Promise<{ error: ClerkError | null }>

SignInFutureFinalizeParams

  • Name
    navigate?
    Type
    (opts: { session: SessionResource }) => Promise<unknown>
    Description

    A custom navigation function to be called just before the session and/or organization is set.

mfa.sendEmailCode()

Sends an email code to sign in with as the second factor.

function sendEmailCode(): Promise<{ error: ClerkError | null }>

mfa.verifyEmailCode()

Verifies an email code sent with the mfa.sendEmailCode() method.

function verifyEmailCode(
  params: SignInFutureMFAEmailCodeVerifyParams,
): Promise<{ error: ClerkError | null }>

SignInFutureMFAEmailCodeVerifyParams

  • Name
    code
    Type
    string
    Description

    The one-time code that was sent to the user as part of the signIn.mfa.sendEmailCode() method.

mfa.sendPhoneCode()

Sends a phone code to sign in with as the second factor.

function sendPhoneCode(): Promise<{ error: ClerkError | null }>

mfa.verifyPhoneCode()

Verifies a phone code sent with the mfa.sendPhoneCode() method.

function verifyPhoneCode(
  params: SignInFutureMFAPhoneCodeVerifyParams,
): Promise<{ error: ClerkError | null }>

SignInFutureMFAPhoneCodeVerifyParams

  • Name
    code
    Type
    string
    Description

    The one-time code that was sent to the user as part of the signIn.mfa.sendPhoneCode() method.

mfa.verifyBackupCode()

Verifies a backup code as a second factor to sign in with.

function verifyBackupCode(
  params: SignInFutureBackupCodeVerifyParams,
): Promise<{ error: ClerkError | null }>

SignInFutureBackupCodeVerifyParams

  • Name
    code
    Type
    string
    Description

    The backup code that was provided to the user when they set up two-step authentication.

mfa.verifyTOTP()

Verifies an authenticator app (TOTP) code as a second factor to sign in with.

function verifyTOTP(params: SignInFutureTOTPVerifyParams): Promise<{ error: ClerkError | null }>

SignInFutureTOTPVerifyParams

  • Name
    code
    Type
    string
    Description

    The TOTP generated by the user's authenticator app.

passkey()

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 passkey(params?: SignInFuturePasskeyParams): Promise<{ error: null | ClerkError }>

SignInFuturePasskeyParams

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

password()

Performs a password-based sign-in.

function password(params: SignInFuturePasswordParams): Promise<{ error: ClerkError | null }>

SignInFuturePasswordParams

  • Name
    password
    Type
    string
    Description

    The user's password. Only supported if password is enabled.

  • Name
    emailAddress
    Type
    string
    Description

    The user's email address. Only supported if Email address is enabled.

  • 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
    phoneNumber
    Type
    string
    Description

    The user's phone number in E.164 format. Only supported if phone number is enabled.

phoneCode.sendCode()

Sends a phone code to sign in with.

function sendCode(params: SignInFuturePhoneCodeSendParams): Promise<{ error: ClerkError | null }>

SignInFuturePhoneCodeSendParams

  • Name
    channel?
    Type
    'sms' | 'whatsapp'
    Description

    The mechanism to use to send the code to the provided phone number. Defaults to 'sms'.

  • Name
    phoneNumber?
    Type
    string
    Description

    The user's phone number in E.164 format. Only supported if phone number is enabled.

  • Name
    phoneNumberId?
    Type
    string
    Description

    The ID for the user's phone number that will receive a message with the one-time authentication code.

phoneCode.verifyCode()

Verifies a phone code sent with the phoneCode.sendCode() method.

function verifyCode(
  params: SignInFuturePhoneCodeVerifyParams,
): Promise<{ error: ClerkError | null }>

SignInFuturePhoneCodeVerifyParams

  • Name
    code
    Type
    string
    Description

    The one-time code that was sent to the user as part of the signIn.phoneCode.sendCode() method.

reset()

Resets the current sign-in attempt by clearing all local state back to null. This is useful when you want to allow users to go back to the beginning of the sign-in flow (e.g., to change their identifier during verification). Unlike other methods, reset() does not trigger the fetchStatus to change to 'fetching' and does not make any API calls - it only clears local state.

function reset(): Promise<{ error: ClerkError | null }>

resetPasswordEmailCode.sendCode()

Sends a password reset code to the first email address on the account.

function sendCode(): Promise<{ error: ClerkError | null }>

resetPasswordEmailCode.submitPassword()

Submits a new password and moves the signIn.status to 'complete'.

function submitPassword(
  params: SignInFutureResetPasswordSubmitParams,
): Promise<{ error: ClerkError | null }>

SignInFutureResetPasswordSubmitParams

  • Name
    password
    Type
    string
    Description

    The new password for the user.

  • Name
    signOutOfOtherSessions?
    Type
    boolean
    Description

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

resetPasswordEmailCode.verifyCode()

Verifies a password reset code sent with the resetPasswordEmailCode.sendCode() method. Will cause signIn.status to become 'needs_new_password'. This is when you will call the resetPasswordEmailCode.submitPassword() method to complete the password reset flow.

function verifyCode(
  params: SignInFutureEmailCodeVerifyParams,
): Promise<{ error: ClerkError | null }>

SignInFutureEmailCodeVerifyParams

  • Name
    code
    Type
    string
    Description

    The one-time code that was sent to the user as part of the signIn.resetPasswordEmailCode.sendCode() method.

resetPasswordPhoneCode.sendCode()

Sends a password reset code to the first phone number on the account.

function sendCode(
  params?: SignInFutureResetPasswordPhoneCodeSendParams,
): Promise<{ error: ClerkError | null }>

SignInFutureResetPasswordPhoneCodeSendParams

resetPasswordPhoneCode.verifyCode()

Verifies a password reset code sent with the resetPasswordPhoneCode.sendCode() method. Will cause signIn.status to become 'needs_new_password'. This is when you will call the resetPasswordPhoneCode.submitPassword() method to complete the password reset flow.

function verifyCode(
  params: SignInFutureResetPasswordPhoneCodeVerifyParams,
): Promise<{ error: ClerkError | null }>

SignInFutureResetPasswordPhoneCodeVerifyParams

  • Name
    code
    Type
    string
    Description

    The one-time code that was sent to the user as part of the signIn.resetPasswordPhoneCode.sendCode() method.

resetPasswordPhoneCode.submitPassword()

Submits a new password and moves the signIn.status to 'complete'.

function submitPassword(
  params: SignInFutureResetPasswordSubmitParams,
): Promise<{ error: ClerkError | null }>

SignInFutureResetPasswordSubmitParams

  • Name
    password
    Type
    string
    Description

    The new password for the user.

  • Name
    signOutOfOtherSessions?
    Type
    boolean
    Description

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

sso()

Performs an SSO-based sign-in (OAuth or Enterprise).

function sso(params: SignInFutureSSOParams): Promise<{ error: ClerkError | null }>

SignInFutureSSOParams

  • Name
    redirectCallbackUrl
    Type
    string
    Description

    The URL to redirect to if a session was not created, and needs additional information.

  • Name
    redirectUrl
    Type
    string
    Description

    The URL to redirect to after the user has completed the SSO flow.

  • Name
    strategy
    Type
    OAuthStrategy | 'enterprise_sso'
    Description

    The strategy to use for authentication.

  • Name
    popup?
    Type
    Window
    Description

    If provided a Window opened via window.open(), the sign-in flow will be performed in a popup window.

  • 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
  • Name
    identifier?
    Type
    string
    Description

    The unique identifier of the user. Only supported with the enterprise_sso strategy.

ticket()

Performs a ticket-based sign-in.

function ticket(params?: SignInFutureTicketParams): Promise<{ error: ClerkError | null }>

SignInFutureTicketParams

  • Name
    ticket
    Type
    string
    Description

    The ticket or token generated from the Backend API.

web3()

Performs a Web3-based sign-in.

function web3(params: SignInFutureWeb3Params): Promise<{ error: ClerkError | null }>

SignInFutureWeb3Params

  • Name
    strategy
    Type
    "web3_base_signature" | "web3_metamask_signature" | "web3_coinbase_wallet_signature" | "web3_okx_wallet_signature" | "web3_solana_signature"
    Description

    The verification strategy to validate the user's sign-in request.

  • Name
    provider
    Type
    "metamask" | "base" | "coinbase_wallet" | "okx_wallet" | "solana"
    Description

    The Web3 wallet provider to use for the sign-in.

  • Name
    walletName?
    Type
    string
    Description

    The name of the wallet to use for Solana sign-ins. Required when provider is set to 'solana'.

Feedback

What did you think of this content?

Last updated on

GitHubEdit on GitHub