SignIn | Clerk

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

Attributes

Name	Type	Description
`status`	`string`	The current status of the sign-in. It can take 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. `needs_second_factor`: Second factor verification (2FA) for the provided identifier needs to be prepared and verified. `complete`: The sign-in is complete and the user is authenticated. `abandoned`: The sign-in has been inactive for a long period of time, thus it's considered as abandoned and need to start over.
`supportedIdentifiers`	`string[]`	Array of all the authentication identifiers that are supported for this sign in. Examples of this could be: `email_address` `phone_number` `web3_wallet` `username`
`identifier`	`string \| null`	The authentication identifier value for the current sign-in.
`supportedExternalAccounts`	`string[]`	Array of all the external accounts that can be used in this sign in. For example: `["oauth_google", "oauth_facebook"]`
`supportedFirstFactors`	`SignInFactor[]`	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. For example: `email_code` for email addresses `phone_code` for phone numbers As well as the identifier that the factor refers to.
`supportedSecondFactors`	`SignInFactor[]`	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, for example: `email_code` for email addresses `totp` for TOTPs As well as the identifier that the factor refers to. Please note that this property is populated only when the first factor is verified.
`firstFactorVerification`	`Verification`	The state of the verification process for the selected first factor. Please note that this property contains an empty verification object initially, since there is no first factor selected. You need to call the `prepareFirstFactor` method in order to start the verification process.
`secondFactorVerification`	`Verification`	The state of the verification process for the selected second factor. Similar to `firstFactorVerification`, this property contains an empty verification object initially, 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.
`userData`	`UserDate`	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.
`createdSessionId`	`string \| null`	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()`


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

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.

Name	Type	Description
`identifier`	`string`	The authentication identifier for the sign in. This can be the value of the user's email address, phone number or username.
`strategy`	`string`	Optional. 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: `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](https://metamask.io/). `oauth_<provider>`: The user will be authenticated with their Social login account. See available OAuth Strategies. `ticket`: The user will be authenticated via a "ticket" or "token" generated from the Backend API.
`password`	`string`	Optional. Supply the user's password, if `password` strategy has been specified.
`ticket`	`string`	Optional. If the strategy is `ticket` you need to provide the ticket or token generated from the Backend API.
`redirectUrl`	`string`	The URL that the OAuth provider should redirect to, on successful authorization on their part. This parameter is required only for OAuth strategies `(oauth_*)`.
`actionCompleteRedirectUrl`	`string`	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 for OAuth strategies `(oauth_*)`.
`transfer`	`boolean`	Transfer the user to a dedicated sign in for an oauth flow.

Returns

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

`resetPassword()`


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

`ResetPasswordParams`

Name	Type	Description
`password`	`string`	The user's current password.
`signOutOfOtherSessions`	`boolean \| undefined`	If `true`, log the user out of all other authenticated sessions.

`createMagicLinkFlow()`


function createMagicLinkFlow(): {
  startMagicLinkFlow: (params: SignInStartMagicLinkFlowParams) => Promise<SignIn>,
  cancelMagicLinkFlow: () => void
}

Sets up a sign in with magic link flow. Calling createMagicLinkFlow() will return two functions. The first function is async and starts the magic link flow, preparing a magic link verification. It sends the magic link email and starts polling for verification results. The signature is startMagicLinkFlow({ 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 cancelMagicLinkFlow() => void.

Returns

createMagicLinkFlow returns an object with two functions:

Name	Type	Description
`startMagicLinkFlow`	`(params: SignInStartMagicLinkFlowParams) => Promise<SignIn>`	Function to start the magic link flow. It prepares a magic link verification and polls for the verification result.
`cancelMagicLinkFlow`	`() => void`	Function to cleanup the magic link flow. Stops waiting for verification results.

Name	Type	Description
`redirectUrl`	`string`	The magic link target URL. Users will be redirected here once they click the magic link from their email.
`emailAddressId`	`string`	The ID of the user's email address that's going to be used as the first factor identification for verification.

Additional methods

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

Need help?

Attributes

Methods

`create()`

Returns

`resetPassword()`

`ResetPasswordParams`

`createMagicLinkFlow()`

Returns

Additional methods

First factor

Second factor

Authenticate with

Attributes

Methods

create()

SignInCreateParams

Returns

resetPassword()

ResetPasswordParams

createMagicLinkFlow()

Returns

SignInStartMagicFlowParams

Additional methods

First factor

Second factor

Authenticate with

`create()`

`SignInCreateParams`

`resetPassword()`

`ResetPasswordParams`

`createMagicLinkFlow()`

`SignInStartMagicFlowParams`