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 object holds the state of the current sign-in attempt and provides methods to drive custom sign-in flows, including first- and second-factor verifications, SSO, ticket-based, and Web3-based authentication.

TKTKTK

Properties

  • Name
    id
    Type
    string | undefined
    Description

    The unique identifier for the current sign-in attempt.

  • Name
    supportedFirstFactors
    Type
    SignInFirstFactor[]
    Description

    The list of first-factor strategies that are available for the current sign-in attempt.

  • Name
    supportedSecondFactors
    Type
    SignInSecondFactor[]
    Description

    The list of second-factor strategies that are available for the current sign-in attempt.

  • 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 custom flow can proceed to signIn.finalize() 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' or 'oauth_provider'.
    • 'needs_second_factor': One of the following second factor verification strategies is missing: 'phone_code' or 'totp'.
    • 'needs_new_password': The user needs to set a new password.
  • 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
    existingSession
    Type
    { sessionId: string } | undefined
    Description

    TKTKTK

  • Name
    firstFactorVerification
    Type
    Verification
    Description

    TKTKTK

  • Name
    secondFactorVerification
    Type
    Verification
    Description

    The second-factor verification for the current sign-in attempt.

  • Name
    identifier
    Type
    string | null
    Description

    The identifier for the current sign-in attempt.

  • Name
    createdSessionId
    Type
    string | null
    Description

    The created session ID for the current sign-in attempt.

  • Name
    userData
    Type
    UserData
    Description

    The user data for the current sign-in attempt.

Methods

create()

Used to supply an identifier for the sign-in attempt. Calling this method will populate data on the sign-in attempt, such as signIn.resource.supportedFirstFactors.

function create(params: SignInFutureCreateParams): Promise<{ error: unknown }>

SignInFutureCreateParams

TKTKTK

  • Name
    identifier?
    Type
    string
    Description

    TKTKTK

  • Name
    strategy?
    Type
    OAuthStrategy | 'saml' | 'enterprise_sso'
    Description

    TKTKTK

  • Name
    redirectUrl?
    Type
    string
    Description

    TKTKTK

  • Name
    actionCompleteRedirectUrl?
    Type
    string
    Description

    TKTKTK

  • Name
    transfer?
    Type
    boolean
    Description

    TKTKTK

  • Name
    ticket?
    Type
    string
    Description

    TKTKTK

password()

Used to submit a password to sign-in.

function password(params: SignInFuturePasswordParams): Promise<{ error: unknown }>

SignInFuturePasswordParams

TKTKTK

One of the following shapes is supported (exactly one identifier field may be provided):

  • { password: string; identifier: string }
  • { password: string; emailAddress: string }
  • { password: string; phoneNumber: string }
  • { password: string }
  • Name
    password
    Type
    string
    Description

    TKTKTK

  • Name
    identifier?
    Type
    string
    Description

    TKTKTK

  • Name
    emailAddress?
    Type
    string
    Description

    TKTKTK

  • Name
    phoneNumber?
    Type
    string
    Description

    TKTKTK

emailCode.sendCode()

Used to send an email code to sign-in

function sendCode(params: SignInFutureEmailCodeSendParams): Promise<{ error: unknown }>

SignInFutureEmailCodeSendParams

TKTKTK

Provide either emailAddress or emailAddressId.

  • Name
    emailAddress?
    Type
    string
    Description

    TKTKTK

  • Name
    emailAddressId?
    Type
    string
    Description

    TKTKTK

emailCode.verifyCode()

Used to verify a code sent via email to sign-in

function verifyCode(params: SignInFutureEmailCodeVerifyParams): Promise<{ error: unknown }>

SignInFutureEmailCodeVerifyParams

TKTKTK

  • Name
    code
    Type
    string
    Description

    TKTKTK

Used to send an email link to sign-in

function sendLink(params: SignInFutureEmailLinkSendParams): Promise<{ error: unknown }>

TKTKTK

Provide either emailAddress or emailAddressId along with verificationUrl.

  • Name
    emailAddress?
    Type
    string
    Description

    TKTKTK

  • Name
    emailAddressId?
    Type
    string
    Description

    TKTKTK

  • Name
    verificationUrl
    Type
    string
    Description

    TKTKTK

Will wait for verification to complete or expire

function waitForVerification(): Promise<{ error: unknown }>

phoneCode.sendCode()

Used to send a phone code to sign-in

function sendCode(params: SignInFuturePhoneCodeSendParams): Promise<{ error: unknown }>

SignInFuturePhoneCodeSendParams

TKTKTK

Provide either phoneNumber or phoneNumberId. Optionally specify the channel.

  • Name
    phoneNumber?
    Type
    string
    Description

    TKTKTK

  • Name
    phoneNumberId?
    Type
    string
    Description

    TKTKTK

  • Name
    channel?
    Type
    PhoneCodeChannel
    Description

    TKTKTK

phoneCode.verifyCode()

Used to verify a code sent via phone to sign-in

function verifyCode(params: SignInFuturePhoneCodeVerifyParams): Promise<{ error: unknown }>

SignInFuturePhoneCodeVerifyParams

TKTKTK

  • Name
    code
    Type
    string
    Description

    TKTKTK

resetPasswordEmailCode.sendCode()

Used to send a password reset code to the first email address on the account

function sendCode(): Promise<{ error: unknown }>

resetPasswordEmailCode.verifyCode()

Used to verify a password reset code sent via email. Will cause signIn.status to become 'needs_new_password'.

function verifyCode(params: SignInFutureEmailCodeVerifyParams): Promise<{ error: unknown }>

SignInFutureEmailCodeVerifyParams

TKTKTK

  • Name
    code
    Type
    string
    Description

    TKTKTK

resetPasswordEmailCode.submitPassword()

Used to submit a new password, and move the signIn.status to 'complete'.

function submitPassword(params: SignInFutureResetPasswordSubmitParams): Promise<{ error: unknown }>

SignInFutureResetPasswordSubmitParams

TKTKTK

  • Name
    password
    Type
    string
    Description

    TKTKTK

  • Name
    signOutOfOtherSessions?
    Type
    boolean
    Description

    TKTKTK

sso()

Used to perform OAuth authentication.

function sso(params: SignInFutureSSOParams): Promise<{ error: unknown }>

SignInFutureSSOParams

TKTKTK

  • Name
    flow?
    Type
    'auto' | 'modal'
    Description

    TKTKTK

  • Name
    strategy
    Type
    OAuthStrategy | 'saml' | 'enterprise_sso'
    Description

    TKTKTK

  • Name
    redirectUrl
    Type
    string
    Description

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

  • Name
    redirectCallbackUrl
    Type
    string
    Description

    TODO @revamp-hooks: This should be handled by FAPI instead.

mfa.sendPhoneCode()

Used to send a phone code as a second factor to sign-in

function sendPhoneCode(): Promise<{ error: unknown }>

mfa.verifyPhoneCode()

Used to verify a phone code sent as a second factor to sign-in

function verifyPhoneCode(params: SignInFutureMFAPhoneCodeVerifyParams): Promise<{ error: unknown }>

SignInFutureMFAPhoneCodeVerifyParams

TKTKTK

  • Name
    code
    Type
    string
    Description

    TKTKTK

mfa.verifyTOTP()

Used to verify a TOTP code as a second factor to sign-in

function verifyTOTP(params: SignInFutureTOTPVerifyParams): Promise<{ error: unknown }>

SignInFutureTOTPVerifyParams

TKTKTK

  • Name
    code
    Type
    string
    Description

    TKTKTK

mfa.verifyBackupCode()

Used to verify a backup code as a second factor to sign-in

function verifyBackupCode(params: SignInFutureBackupCodeVerifyParams): Promise<{ error: unknown }>

SignInFutureBackupCodeVerifyParams

TKTKTK

  • Name
    code
    Type
    string
    Description

    TKTKTK

ticket()

Used to perform a ticket-based sign-in.

function ticket(params?: SignInFutureTicketParams): Promise<{ error: unknown }>

SignInFutureTicketParams

TKTKTK

  • Name
    ticket
    Type
    string
    Description

    TKTKTK

web3()

Used to perform a Web3-based sign-in.

function web3(params: SignInFutureWeb3Params): Promise<{ error: unknown }>

SignInFutureWeb3Params

TKTKTK

  • Name
    strategy
    Type
    Web3Strategy
    Description

    TKTKTK

finalize()

Used to convert 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: unknown }>

SignInFutureFinalizeParams

TKTKTK

  • Name
    navigate?
    Type
    SetActiveNavigate
    Description

    TKTKTK

Types

The shape of emailLink.verification when present.

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

    The verification status

  • Name
    createdSessionId
    Type
    string
    Description

    The created session ID

  • Name
    verifiedFromTheSameClient
    Type
    boolean
    Description

    Whether the verification was from the same client

ExistingSession

The shape of existingSession when present.

  • Name
    sessionId
    Type
    string
    Description

    TKTKTK

Feedback

What did you think of this content?
GitHubEdit on GitHub

Last updated on