`SignInFuture` object

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

Example

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

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
Indicates that the sign-in was not able to create a new session because the identifier already exists in an existing session.
Name
existingSession.sessionId
Type
string
Description
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.

'complete' - The sign-in process has been completed successfully.

'needs_client_trust' - The user is signing in from a new device and must complete a second factor verification to establish Client Trust. See the Client Trust custom flow guide for more information.

'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', 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 second factor verification 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.

'firstName': The user's first name.

'lastName': The user's last name.

'imageUrl': The user's profile image URL.

'hasImage': Whether the user has a profile image.

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. Once the sign-in process is complete, call the signIn.finalize() method to set the newly created session as the active session.

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.

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.

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

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
password?
Type
string
Description
The user's password. Only supported if password is enabled.
Name
redirectUrl?
Type
string
Description
The full URL or path that the OAuth provider should redirect to after successful authorization on their part.
Name
signUpIfMissing?
Type
boolean
Description
When set to true, if a user does not exist, the sign-up will prepare a transfer to sign up a new account. If bot sign-up protection is enabled, captcha will also be required on sign in.
Name
strategy?
Type
OAuthStrategy | "passkey" | "enterprise_sso" | "ticket"
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
Required if strategy is set to 'ticket'. The ticket or token generated from the Backend API.
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.

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

Name
emailAddress?
Type
string
Description
The user's email address. Only supported if Email address is enabled. Provide either emailAddress or emailAddressId, not both. Omit both when a sign-in already exists.
Name
emailAddressId?
Type
string
Description
The ID for the user's email address that will receive an email with the one-time authentication code. Provide either emailAddress or emailAddressId, not both. Omit both when a sign-in already exists.

`emailCode.verifyCode()`

Verifies a code sent with the emailCode.sendCode() method.

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

Name
code
Type
string
Description
The one-time code that was sent to the user.

`emailLink.sendLink()`

Sends an email link to sign in with.

function sendLink(params: SignInFutureEmailLinkSendParams): Promise<{ error: null | ClerkError }>

Name
emailAddress?
Type
string
Description
The user's email address. Only supported if Email address is enabled. Provide either emailAddress or emailAddressId, not both. Omit both when a sign-in already exists.
Name
emailAddressId?
Type
string
Description
The ID for the user's email address that will receive an email with the email link. Provide either emailAddress or emailAddressId, not both. Omit both when a sign-in already exists.
Name
verificationUrl
Type
string
Description
The full URL that the user will be redirected to when they visit the email link.

`emailLink.verification`

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
createdSessionId
Type
string
Description
The ID of the session that was created upon completion of the current sign-in.
Name
status
Type
"expired" | "failed" | "verified" | "client_mismatch"
Description
The verification status.
Name
verifiedFromTheSameClient
Type
boolean
Description
Whether the verification was from the same client.

`emailLink.waitForVerification()`

Waits for email link verification to complete or expire.

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

`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: null | ClerkError }>

Name
navigate?
Type
SetActiveNavigate
Description
A custom navigation function to be called just before the session and/or Organization is set. When provided, it takes precedence over the redirectUrl parameter for navigation. The callback receives a decorateUrl function that should be used to wrap destination URLs. This enables Safari ITP cookie refresh when needed. The decorated URL may be an external URL (starting with https://) that requires window.location.href instead of client-side navigation. See the section on using the navigate() parameter for more details.

`mfa.sendEmailCode()`

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

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

`mfa.verifyEmailCode()`

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

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

Name
code
Type
string
Description
The one-time code that was sent to the user.

`mfa.sendPhoneCode()`

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

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

`mfa.verifyPhoneCode()`

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

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

Name
code
Type
string
Description
The one-time code that was sent to the user.

`mfa.verifyBackupCode()`

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

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

Name
code
Type
string
Description
The backup code that was provided to the user when they set up backup codes.

`mfa.verifyTOTP()`

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

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

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

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

Submits a password to sign-in.

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

Name
emailAddress
Type
string
Description
The user's email address. Only supported if Email address is enabled. Provide exactly one of identifier, emailAddress, or phoneNumber.
Name
identifier
Type
string
Description
The authentication identifier for the sign-in (email address, phone number, username, or Web3 wallet address). Provide exactly one of identifier, emailAddress, or phoneNumber. Omit all when a sign-in already exists to use the current identifier.
Name
password
Type
string
Description
The user's password. Only supported if password is enabled.
Name
phoneNumber
Type
string
Description
The user's phone number in E.164 format. Only supported if phone number is enabled. Provide exactly one of identifier, emailAddress, or phoneNumber.

`phoneCode.sendCode()`

Sends a phone code to sign in with.

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

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. Provide either phoneNumber or phoneNumberId, not both. Omit both when a sign-in already exists.
Name
phoneNumberId
Type
string
Description
The ID for the user's phone number that will receive a message with the one-time authentication code. Provide either phoneNumber or phoneNumberId, not both. Omit both when a sign-in already exists.

`phoneCode.verifyCode()`

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

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

Name
code
Type
string
Description
The one-time code that was sent to the user.

`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: null | ClerkError }>

`resetPasswordEmailCode.sendCode()`

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

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

`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: null | ClerkError }>

Name
code
Type
string
Description
The one-time code that was sent to the user.

`resetPasswordEmailCode.submitPassword()`

Submits a new password and moves the sign-in status to 'complete'.

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

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.

`resetPasswordPhoneCode.sendCode()`

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

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

Name
phoneNumber?
Type
string
Description
The user's phone number in E.164 format. Only supported if phone number is enabled.

`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: null | ClerkError }>

Name
code
Type
string
Description
The one-time code that was sent to the user.

`resetPasswordPhoneCode.submitPassword()`

Submits a new password and moves the sign-in status to 'complete'.

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

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 (Social/OAuth or Enterprise).

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

Name
enterpriseConnectionId?
Type
string
Description
The identifier of the enterprise connection to target when using the enterprise_sso strategy.
Name
identifier?
Type
string
Description
The unique identifier of the user. Only supported with the enterprise_sso strategy.
Name
oidcPrompt?
Type
string
Description
The value to pass to the OIDC prompt parameter in the generated OAuth redirect URL.
Name
popup?
Type
Window
Description
If provided, a Window to use for the OAuth flow. Useful in instances where you cannot navigate to an OAuth provider.
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.

`ticket()`

Performs a ticket-based sign-in.

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

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: null | ClerkError }>

Name
provider
Type
"metamask" | "base" | "coinbase_wallet" | "okx_wallet" | "solana"
Description
The Web3 wallet provider to use for the sign-in.
Name
strategy
Type
"web3_metamask_signature" | "web3_base_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
walletName?
Type
string
Description
Required when provider is set to 'solana'. The name of the wallet to use for Solana sign-ins.

Last updated on Jun 4, 2026

Edit on GitHub

SignInFuture object

Feedback

`SignInFuture` object