Properties
Methods
Additional methods

`SignIn`

The SignIn object holds all the state of the current sign in and provides helper methods to navigate and complete the sign in process.

There are two important steps in the sign in flow.

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 public address or providing proof of their identity through an external social account (SSO/OAuth).
After that, users might need to go through a second verification process. This is the second factor (2FA).

The SignIn object's properties can be split into logical groups, with each group providing information on different aspects of the sign in flow. These groups can be:

Information about the current sign in status in general and which authentication identifiers, authentication methods and verifications are supported.
Information about the user and the provided authentication identifier value (email address, phone number or username).Information about each verification, either the first factor (logging in) or the second factor (2FA).

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

Use this method to kick-off the sign in flow. It creates a SignIn object and stores the sign-in lifecycle state.

Depending on the use-case and the params you pass to the create method, it can either complete the sign-in process in one go, or simply collect part of the necessary data for completing authentication at a later stage.

function create(params: SignInCreateParams): Promise<SignIn>;

`SignInCreateParams`

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's identifier value. Each authentication identifier supports different verification strategies.
Possible strategy 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. The email_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. The email_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. The phone_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 public address. The web3_wallet_id parameter can also be specified to select which of the user's known web3 wallets will be used. Currently Clerk supports Metamask.
oauth_<provider>: The user will be authenticated with their social sign-in account. See available OAuth providers.
ticket: The user will be authenticated via the ticket or token generated from the Backend API.
Name
password?
Type
string
Description
Supply the user's password. This parameter is required only if strategy is set to password.
Name
ticket?
Type
string
Description
Provide the ticket or token generated from the Backend API. This parameter is required only if strategy is set to ticket.
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 like oauth_<provider>. If you set the strategy param to email_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 like oauth_<provider>.
Name
transfer?
Type
boolean
Description
Transfer the user to a dedicated sign-in for an OAuth flow.

`create()` returns

Type	Description
`Promise<SignIn>`	This method returns a `Promise` which resolves with a `SignIn` object. Check the `status` attribute to see if the sign-in has been completed or a hint on what needs to happen next.

`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.

`resetPassword()` returns

Type	Description
`Promise<[SignIn][signin-ref]>`	A `Promise` which resolves with a [`SignIn`][signin-ref] object.

`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.

function createEmailLinkFlow(): {
  startEmailLinkFlow: (params: SignInStartEmailLinkFlowParams) => Promise<SignIn>,
  cancelEmailLinkFlow: () => void
}

`createEmailLinkFlow()` returns

createEmailLinkFlow returns an object with two functions:

Name
startEmailLinkFlow
Type
(params: SignInStartEmailLinkFlowParams) => Promise<[SignIn][signin-ref]>
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.

`SignInStartEmailLinkFlowParams`

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 (deprecated)
Type
string
Description
The email link target URL. Users will be redirected here once they click the email link from their email. signInFallbackRedirectUrl has priority over the legacy redirectUrl. Use fallbackRedirectUrl or forceRedirectUrl instead of redirectUrl.

SignIn

SignInCreateParams

create() returns

ResetPasswordParams

resetPassword() returns

createEmailLinkFlow() returns

SignInStartEmailLinkFlowParams