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:
- Initiate the sign-in process by collecting the user's authentication information and passing the appropriate parameters to the
create()
method. - 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).
- Attempt to complete the first factor verification.
- 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.
- Attempt to complete the second factor verification.
- If verification is successful, set the newly created session as the active session by passing the
SignIn.createdSessionId
to thesetActive()
method on theClerk
object.
Properties
- Name
status
- Type
SignInStatus
- Description
The current status of the sign-in.
SignInStatus
supports the following values:needs_identifier
: The authentication identifier hasn't been provided.needs_first_factor
: First factor verification for the provided identifier needs to be prepared and verified. See First Factor for details.needs_second_factor
: Second factor verification (2FA) for the provided identifier needs to be prepared and verified. See Second Factor for details.needs_new_password
: The user needs to set a new password.complete
: The sign-in is complete and the user is authenticated.
- 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
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 theprepareSecondFactor
method in order to start the verification process. For thetotp
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 notcomplete
.
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.
- 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 or username.
- Name
strategy?
- Type
string
- Description
Select the first factor verification strategy. The
strategy
value depends on the object'sidentifier
value. Each authentication identifier supports different verification strategies. Possiblestrategy
values are:password
: The verification will attempt to be completed using the user's password.email_link
: User will receive an email magic link via email. Theemail_address_id
parameter can also be specified to select one of the user's known email addresses.email_code
: User will receive a one-time authentication code via email. At least one email address should be on file for the user. Theemail_address_id
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 in their phone, via SMS. At least one phone number should be on file for the user. Thephone_number_id
parameter can also be specified to select which of the user's known phone numbers the SMS will go to.web3_metamask_signature
: The verification will attempt to be completed using the user's Web3 wallet address via Metamask. Theweb3_wallet_id
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. Theweb3_wallet_id
parameter can also be specified to select which of the user's known Web3 wallets will be used.oauth_<provider>
: The user will be authenticated with their social sign-in account. See available social providers.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 useauthenticateWithGoogleOneTap()
instead, as it will also set the user's current session as active for you.
- Name
password?
- Type
string
- Description
Supply the user's password. This parameter is required only if
strategy
is set topassword
.
- Name
ticket?
- Type
string
- Description
Provide the ticket or token generated from the Backend API. This parameter is required only if
strategy
is set toticket
.
- Name
redirectUrl?
- Type
string
- Description
The URL that the OAuth provider should redirect to, on successful authorization on their part. This parameter is required only if
strategy
is set to an OAuth strategy likeoauth_<provider>
. If you set thestrategy
param toemail_link
, this parameter is optional.
- 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. This parameter is required only if
strategy
is set to an OAuth strategy likeoauth_<provider>
.
- Name
transfer?
- Type
boolean
- Description
Transfer the user to a dedicated sign-in for an OAuth flow.
resetPassword()
Resets a user's password.
- 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.
createEmailLinkFlow()
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
.
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 email link target URL. Users will be redirected here once they click the email link from their email.
Additional methods
In addition to the methods listed above, the SignIn
class also has the following methods:
First factor
Second factor
Authenticate with
authenticateWithRedirect()
authenticateWithMetamask()
authenticateWithCoinbaseWallet()
authenticateWithWeb3()
Example
For examples of how to access the SignUp
object and use the associated methods, see the custom flow guides.
Feedback
Last updated on