Skip to main content
Docs

SignIn

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 first factor verification. Users must complete a first factor verification. This can be something like providing a password, an email link, a one-time code (OTP), 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.
  4. Optionally, if you have enabled multi-factor for your application, you will need to prepare the second factor verification for users who have set up 2FA for their account.
  5. Attempt to complete the second factor verification.
  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.

Properties

  • 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 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_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
    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 first factors 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 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. See the SignInSecondFactor type reference for more information.

  • Name
    firstFactorVerification
    Type
    Verification
    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. You need to call the prepareFirstFactor method in order to start the verification process.

  • Name
    secondFactorVerification
    Type
    Verification
    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. 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.

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

Methods

create()

Returns a new SignIn object based on the params you pass to it, and stores the sign-in lifecycle state in the status property. Use this method to initiate the sign-in process.

What you must pass to params depends on which sign-in options you have enabled in your Clerk application instance.

Optionally, you can complete the sign-in process, fully authenticating the user 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' | 'oauth_<provider>' | 'saml' | 'enterprise_sso' | 'passkey' | 'web3_metamask_signature' | 'web3_coinbase_wallet_signature' | 'web3_okx_wallet_signature' | 'ticket' | 'google_one_tap'
    Description

    The first factor verification 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 a one-time authentication code via email. The identifier parameter can also be specified to select one of the user's known email addresses.
    • 'phone_code': User will receive a one-time authentication code 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>.
    • 'saml' (deprecated): Deprecated in favor of 'enterprise_sso'. The user will be authenticated with their SAML account.
    • '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_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.
    • '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.

resetPassword()

Resets a user's password.

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

ResetPasswordParams

  • Name
    password
    Type
    string
    Description

    The user's current password.

  • Name
    signOutOfOtherSessions?
    Type
    boolean | undefined
    Description

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

Sets up a sign in with email link flow. Calling createemailLinkFlow() will return two functions. The first function is async and starts the email link flow, preparing a email link verification. It sends the email link email and starts polling for verification results. The signature is startEmailLinkFlow({ redirectUrl: string, emailAddressId: string }) => Promise<SignInResource>.

The second function can be used to stop polling at any time, allowing for full control of the flow and cleanup. The signature is cancelEmailLinkFlow() => void.

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 URL that the user will be redirected to when they visit the email link.

Additional methods

In addition to the methods listed above, the SignIn class also has the following methods:

First factor

Second factor

Authenticate with

Example

For examples of how to access the SignIn object and use the associated methods, see the custom flow guides.

Feedback

What did you think of this content?
Edit this page on GitHub

Last updated on