# 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](https://clerk.com/docs/guides/development/custom-flows/overview.md?sdk=nextjs) for comprehensive examples of using the `SignInFuture` object to build custom user interfaces with the Clerk API. ## Properties | Property | Type | Description | | ---------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `createdSessionId` | `null | string` | 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'`. | | `existingSession?` | `{ sessionId: string; }` | Indicates that the sign-in was not able to create a new session because the identifier already exists in an existing session. | | `existingSession.sessionId` | `string` | The ID of the existing session. | | `firstFactorVerification` | [VerificationResource](https://clerk.com/docs/nextjs/reference/types/verification-resource.md) | 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. | | `id?` | `string` | The unique identifier for the current sign-in attempt. | | `identifier` | `null | string` | The authentication identifier value for the current sign-in. `null` if the `strategy` is `'oauth_'` or `'enterprise_sso'`. | | `isTransferable` | `boolean` | 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. | | `secondFactorVerification` | [VerificationResource](https://clerk.com/docs/nextjs/reference/types/verification-resource.md) | 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. | | `status` | `SignInStatus` | The current status of the sign-in. | | `supportedFirstFactors` | SignInFirstFactor[] | 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. | | `supportedSecondFactors` | SignInSecondFactor[] | 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. | | `userData` | `UserData` | 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. 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](https://clerk.com/docs/guides/configure/auth-strategies/sign-up-sign-in-options.md?sdk=nextjs) 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. > 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. ```typescript function create(params: SignInFutureCreateParams): Promise<{ error: null | ClerkError }> ``` #### `SignInFutureCreateParams` | Property | Type | Description | | ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `actionCompleteRedirectUrl?` | `string` | The URL that the user will be redirected to, after successful authorization from the OAuth provider and Clerk sign-in. | | `identifier?` | `string` | 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. | | `password?` | `string` | The user's password. Only supported if [password](https://clerk.com/docs/guides/configure/auth-strategies/sign-up-sign-in-options.md?sdk=nextjs#password) is enabled. | | `redirectUrl?` | `string` | The full URL or path that the OAuth provider should redirect to after successful authorization on their part. | | `signUpIfMissing?` | `boolean` | 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. | | `strategy?` | OAuthStrategy | "passkey" | "enterprise_sso" | "ticket" | The first factor verification strategy to use in the sign-in flow. Depends on the `identifier` value. Each authentication identifier supports different verification strategies. | | `ticket?` | `string` | **Required** if `strategy` is set to `'ticket'`. The [ticket _or token_](https://clerk.com/docs/guides/development/custom-flows/authentication/application-invitations.md?sdk=nextjs) generated from the Backend API. | | `transfer?` | `boolean` | 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. ```typescript function sendCode(params?: SignInFutureEmailCodeSendParams): Promise<{ error: null | ClerkError }> ``` #### `SignInFutureEmailCodeSendParams` | Property | Type | Description | | ----------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `emailAddress?` | `string` | The user's email address. Only supported if [Email address](https://clerk.com/docs/guides/configure/auth-strategies/sign-up-sign-in-options.md?sdk=nextjs#email) is enabled. Provide either `emailAddress` or `emailAddressId`, not both. Omit both when a sign-in already exists. | | `emailAddressId?` | `string` | 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()](https://clerk.com/docs/nextjs/reference/objects/sign-in-future.md#email-code-send-code) method. ```typescript function verifyCode(params: SignInFutureEmailCodeVerifyParams): Promise<{ error: null | ClerkError }> ``` #### `SignInFutureEmailCodeVerifyParams` | Property | Type | Description | | ------------------------ | -------- | -------------------------------------------- | | `code` | `string` | The one-time code that was sent to the user. | ### `emailLink.sendLink()` Sends an email link to sign in with. ```typescript function sendLink(params: SignInFutureEmailLinkSendParams): Promise<{ error: null | ClerkError }> ``` #### `SignInFutureEmailLinkSendParams` | Property | Type | Description | | ----------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `emailAddress?` | `string` | The user's email address. Only supported if [Email address](https://clerk.com/docs/guides/configure/auth-strategies/sign-up-sign-in-options.md?sdk=nextjs#email) is enabled. Provide either `emailAddress` or `emailAddressId`, not both. Omit both when a sign-in already exists. | | `emailAddressId?` | `string` | 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. | | `verificationUrl` | `string` | 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. | Property | Type | Description | | --------------------------- | ------------------------------------------------------------------ | ------------------------------------------------------------------------------ | | `createdSessionId` | `string` | The ID of the session that was created upon completion of the current sign-in. | | `status` | `"expired" | "failed" | "verified" | "client_mismatch"` | The verification status. | | `verifiedFromTheSameClient` | `boolean` | Whether the verification was from the same client. | ### `emailLink.waitForVerification()` Waits for email link verification to complete or expire. ```typescript 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()](https://clerk.com/docs/nextjs/reference/hooks/use-user.md) hook) to update automatically. ```typescript function finalize(params?: SignInFutureFinalizeParams): Promise<{ error: null | ClerkError }> ``` #### `SignInFutureFinalizeParams` | Property | Type | Description | | --------------------------------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `navigate?` | `SetActiveNavigate` | 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](https://clerk.com/docs/nextjs/reference/objects/clerk.md#using-the-navigate-parameter) for more details. | ### `mfa.sendEmailCode()` Sends an email code to sign in with as a second factor. ```typescript function sendEmailCode(): Promise<{ error: null | ClerkError }> ``` ### `mfa.verifyEmailCode()` Verifies an email code sent with the [mfa.sendEmailCode()](https://clerk.com/docs/nextjs/reference/objects/sign-in-future.md#mfa-send-email-code) method. ```typescript function verifyEmailCode(params: SignInFutureMFAEmailCodeVerifyParams): Promise<{ error: null | ClerkError }> ``` #### `SignInFutureMFAEmailCodeVerifyParams` | Property | Type | Description | | ------------------------ | -------- | -------------------------------------------- | | `code` | `string` | The one-time code that was sent to the user. | ### `mfa.sendPhoneCode()` Sends a phone code to sign in with as a second factor. ```typescript function sendPhoneCode(): Promise<{ error: null | ClerkError }> ``` ### `mfa.verifyPhoneCode()` Verifies a phone code sent with the [mfa.sendPhoneCode()](https://clerk.com/docs/nextjs/reference/objects/sign-in-future.md#mfa-send-phone-code) method. ```typescript function verifyPhoneCode(params: SignInFutureMFAPhoneCodeVerifyParams): Promise<{ error: null | ClerkError }> ``` #### `SignInFutureMFAPhoneCodeVerifyParams` | Property | Type | Description | | ------------------------ | -------- | -------------------------------------------- | | `code` | `string` | The one-time code that was sent to the user. | ### `mfa.verifyBackupCode()` Verifies a backup code to sign in with as a second factor. ```typescript function verifyBackupCode(params: SignInFutureBackupCodeVerifyParams): Promise<{ error: null | ClerkError }> ``` #### `SignInFutureBackupCodeVerifyParams` | Property | Type | Description | | ------------------------ | -------- | ---------------------------------------------------------------------------- | | `code` | `string` | 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. ```typescript function verifyTOTP(params: SignInFutureTOTPVerifyParams): Promise<{ error: null | ClerkError }> ``` #### `SignInFutureTOTPVerifyParams` | Property | Type | Description | | ------------------------ | -------- | --------------------------------------------------- | | `code` | `string` | 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. ```typescript function passkey(params?: SignInFuturePasskeyParams): Promise<{ error: null | ClerkError }> ``` #### `SignInFuturePasskeyParams` | Property | Type | Description | | ------------------------- | ---------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `flow?` | `"autofill" | "discoverable"` | The flow to use for the passkey sign-in. | ### `password()` Submits a password to sign-in. ```typescript function password(params: SignInFuturePasswordParams): Promise<{ error: null | ClerkError }> ``` #### `SignInFuturePasswordParams` | Property | Type | Description | | -------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `emailAddress` | `string` | The user's email address. Only supported if [Email address](https://clerk.com/docs/guides/configure/auth-strategies/sign-up-sign-in-options.md?sdk=nextjs#email) is enabled. Provide exactly one of `identifier`, `emailAddress`, or `phoneNumber`. | | `identifier` | `string` | 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. | | `password` | `string` | The user's password. Only supported if [password](https://clerk.com/docs/guides/configure/auth-strategies/sign-up-sign-in-options.md?sdk=nextjs#password) is enabled. | | `phoneNumber` | `string` | The user's phone number in [E.164 format](https://en.wikipedia.org/wiki/E.164). Only supported if [phone number](https://clerk.com/docs/guides/configure/auth-strategies/sign-up-sign-in-options.md?sdk=nextjs#phone) is enabled. Provide exactly one of `identifier`, `emailAddress`, or `phoneNumber`. | ### `phoneCode.sendCode()` Sends a phone code to sign in with. ```typescript function sendCode(params?: SignInFuturePhoneCodeSendParams): Promise<{ error: null | ClerkError }> ``` #### `SignInFuturePhoneCodeSendParams` | Property | Type | Description | | --------------- | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `channel?` | `"sms" | "whatsapp"` | The mechanism to use to send the code to the provided phone number. Defaults to `'sms'`. | | `phoneNumber?` | `string` | The user's phone number in [E.164 format](https://en.wikipedia.org/wiki/E.164). Only supported if [phone number](https://clerk.com/docs/guides/configure/auth-strategies/sign-up-sign-in-options.md?sdk=nextjs#phone) is enabled. Provide either `phoneNumber` or `phoneNumberId`, not both. Omit both when a sign-in already exists. | | `phoneNumberId` | `string` | 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()](https://clerk.com/docs/nextjs/reference/objects/sign-in-future.md#phone-code-send-code) method. ```typescript function verifyCode(params: SignInFuturePhoneCodeVerifyParams): Promise<{ error: null | ClerkError }> ``` #### `SignInFuturePhoneCodeVerifyParams` | Property | Type | Description | | ------------------------ | -------- | -------------------------------------------- | | `code` | `string` | 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. ```typescript function reset(): Promise<{ error: null | ClerkError }> ``` ### `resetPasswordEmailCode.sendCode()` Sends a password reset code to the first email address on the account. ```typescript function sendCode(): Promise<{ error: null | ClerkError }> ``` ### `resetPasswordEmailCode.verifyCode()` Verifies a password reset code sent with the [resetPasswordEmailCode.sendCode()](https://clerk.com/docs/nextjs/reference/objects/sign-in-future.md#reset-password-email-code-send-code) method. Will cause `signIn.status` to become `'needs_new_password'`. This is when you will call the [resetPasswordEmailCode.submitPassword()](https://clerk.com/docs/nextjs/reference/objects/sign-in-future.md#reset-password-email-code-submit-password) method to complete the password reset flow. ```typescript function verifyCode(params: SignInFutureEmailCodeVerifyParams): Promise<{ error: null | ClerkError }> ``` #### `SignInFutureEmailCodeVerifyParams` | Property | Type | Description | | ------------------------ | -------- | -------------------------------------------- | | `code` | `string` | The one-time code that was sent to the user. | ### `resetPasswordEmailCode.submitPassword()` Submits a new password and moves the sign-in status to `'complete'`. ```typescript function submitPassword(params: SignInFutureResetPasswordSubmitParams): Promise<{ error: null | ClerkError }> ``` #### `SignInFutureResetPasswordSubmitParams` | Property | Type | Description | | ------------------------------------------------------------- | --------- | ------------------------------------------------------------------ | | `password` | `string` | The new password for the user. | | `signOutOfOtherSessions?` | `boolean` | 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. ```typescript function sendCode(params?: SignInFutureResetPasswordPhoneCodeSendParams): Promise<{ error: null | ClerkError }> ``` #### `SignInFutureResetPasswordPhoneCodeSendParams` | Property | Type | Description | | --------------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `phoneNumber?` | `string` | The user's phone number in [E.164 format](https://en.wikipedia.org/wiki/E.164). Only supported if [phone number](https://clerk.com/docs/guides/configure/auth-strategies/sign-up-sign-in-options.md?sdk=nextjs#phone) is enabled. | ### `resetPasswordPhoneCode.verifyCode()` Verifies a password reset code sent with the [resetPasswordPhoneCode.sendCode()](https://clerk.com/docs/nextjs/reference/objects/sign-in-future.md#reset-password-phone-code-send-code) method. Will cause `signIn.status` to become `'needs_new_password'`. This is when you will call the [resetPasswordPhoneCode.submitPassword()](https://clerk.com/docs/nextjs/reference/objects/sign-in-future.md#reset-password-phone-code-submit-password) method to complete the password reset flow. ```typescript function verifyCode(params: SignInFutureResetPasswordPhoneCodeVerifyParams): Promise<{ error: null | ClerkError }> ``` #### `SignInFutureResetPasswordPhoneCodeVerifyParams` | Property | Type | Description | | ------------------------ | -------- | -------------------------------------------- | | `code` | `string` | The one-time code that was sent to the user. | ### `resetPasswordPhoneCode.submitPassword()` Submits a new password and moves the sign-in status to `'complete'`. ```typescript function submitPassword(params: SignInFutureResetPasswordSubmitParams): Promise<{ error: null | ClerkError }> ``` #### `SignInFutureResetPasswordSubmitParams` | Property | Type | Description | | ------------------------------------------------------------- | --------- | ------------------------------------------------------------------ | | `password` | `string` | The new password for the user. | | `signOutOfOtherSessions?` | `boolean` | If `true`, signs the user out of all other authenticated sessions. | ### `sso()` Performs an SSO-based sign-in (Social/OAuth or Enterprise). ```typescript function sso(params: SignInFutureSSOParams): Promise<{ error: null | ClerkError }> ``` #### `SignInFutureSSOParams` | Property | Type | Description | | ------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `enterpriseConnectionId?` | `string` | The identifier of the enterprise connection to target when using the `enterprise_sso` strategy. | | `identifier?` | `string` | The unique identifier of the user. Only supported with the `enterprise_sso` strategy. | | `oidcPrompt?` | `string` | The value to pass to the [OIDC prompt parameter](https://openid.net/specs/openid-connect-core-1_0.html#:~:text=prompt,reauthentication%20and%20consent.) in the generated OAuth redirect URL. | | `popup?` | `Window` | If provided, a `Window` to use for the OAuth flow. Useful in instances where you cannot navigate to an OAuth provider. | | `redirectCallbackUrl` | `string` | The URL to redirect to if a session was not created, and needs additional information. | | `redirectUrl` | `string` | The URL to redirect to after the user has completed the SSO flow. | | `strategy` | OAuthStrategy | "enterprise_sso" | The strategy to use for authentication. | ### `ticket()` Performs a ticket-based sign-in. ```typescript function ticket(params?: SignInFutureTicketParams): Promise<{ error: null | ClerkError }> ``` #### `SignInFutureTicketParams` | Property | Type | Description | | ---------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `ticket` | `string` | The [ticket _or token_](https://clerk.com/docs/guides/development/custom-flows/authentication/application-invitations.md?sdk=nextjs) generated from the Backend API. | ### `web3()` Performs a Web3-based sign-in. ```typescript function web3(params: SignInFutureWeb3Params): Promise<{ error: null | ClerkError }> ``` #### `SignInFutureWeb3Params` | Property | Type | Description | | ------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- | | `provider` | `"metamask" | "base" | "coinbase_wallet" | "okx_wallet" | "solana"` | The Web3 wallet provider to use for the sign-in. | | `strategy` | `"web3_metamask_signature" | "web3_base_signature" | "web3_coinbase_wallet_signature" | "web3_okx_wallet_signature" | "web3_solana_signature"` | The verification strategy to validate the user's sign-in request. | | `walletName?` | `string` | **Required** when `provider` is set to `'solana'`. The name of the wallet to use for Solana sign-ins. | --- ## Sitemap [Overview of all docs pages](https://clerk.com/docs/llms.txt)