SignIn

The SignIn object contains the state of the current sign-in that the user has initiated.

Overview

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 or 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, e.g. oauth_google, oauth_facebook, etc.
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, e.g. email_code for email addresses, phone_code for phone numbers, etc., as well as the identifier that the factor refers to.
supportedSecondFactors	SignInFactor[] \| null	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, e.g. email_code for email addresses, phone_code for phone numbers, totp for TOTPs, etc., 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	VerificationResource	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 `SignIn.prepareFirstFactor` method in order to start the verification process.
secondFactorVerification	VerificationResource	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 `SignIn.prepareSecondFactor` method in order to start the verification process. For the `totp` strategy you can directly attempt.
userData	UserDate \| null	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(params)

create(params: SignInCreateParams) => Promise<SignInResource>

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.

Parameters

Name	Description
params	SignInCreateParams Depending on the keys and values passed here, the create method's behavior changes.

Returns

Type	Description
Promise<SignInResource>	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.

prepareFirstFactor(params)

prepareFirstFactor(params: PrepareFirstFactorParams) => Promise<SignInResource>

Begins the first factor verification process. This is a required step in order to complete a sign in, as users should be verified at least by one factor of authentication.

Common scenarios are one-time code (OTP) or social account (SSO) verification. This is determined by the accepted strategy parameter values. Each authentication identifier supports different strategies.

Parameters

Name	Description
params	PrepareFirstFactorParams An object that allows you to specify a verification strategy and any strategy-specific additional data.

Returns

Type	Description
Promise<SignInResource>	This method returns a `Promise` which resolves with a `SignIn` object. Check the `firstFactorVerification` attribute for the status of the first factor verification process.

attemptFirstFactor(params)

attemptFirstFactor(params: AttemptFirstFactorParams) => Promise<SignInResource>

Attempts to complete the first factor verification process. This is a required step in order to complete a sign in, as users should be verified at least by one factor of authentication.

Make sure that a SignIn object already exists before you call this method, either by first calling SignIn.create or SignIn.prepareFirstFactor. The only strategy that does not require a verification to have already been prepared before attempting to complete it, is the password strategy.

Depending on the strategy that was selected when the verification was prepared, the method parameters should be different.

Parameters

Name	Description
params	AttemptFirstFactorParams An object that includes the verification strategy and the evidence that's needed to identify the user and complete the verification process.

Returns

Type	Description
Promise<SignInResource>	This method returns a `Promise` which resolves with a `SignIn` object. Check the `firstFactorVerification` attribute for the status of the first factor verification process.

prepareSecondFactor(params)

prepareSecondFactor(params: PrepareSecondFactorParams) => Promise<SignInResource>

Begins the second factor verification process. This step is optional in order to complete a sign in.

A common scenario for the second step verification (2FA) is to require a one-time code (OTP) as proof of identity. This is determined by the accepted strategy parameter values. Each authentication identifier supports different strategies.

Note: while th phone_code strategy requires preparation, the totp strategy does not - the user can directly attempt the second factor verification in that case.

Parameters

Name	Description
params	PrepareSecondFactorParams An object that specifies the verification strategy.

Returns

Type	Description
Promise<SignInResource>	This method returns a `Promise` which resolves with a `SignIn` object. Check the `secondFactorVerification` attribute for the status of the second factor verification process.

attemptSecondFactor(params)

attemptSecondFactor(params: AttemptSecondFactorParams) => Promise<SignInResource>

Attempts to complete the second factor verification process (2FA). This step is optional in order to complete a sign in.

For the phone_code strategy, make sure that a verification has already been prepared before you call this method, by first calling SignIn.prepareSecondFactor. Depending on the strategy that was selected when the verification was prepared, the method parameters should be different.

The totp strategy can directly be attempted, without the need for preparation.

Parameters

Name	Description
params	AttemptSecondFactorParams An object that specifies a verification strategy and any strategy-specific additional data.

Returns

Type	Description
Promise<SignInResource>	This method returns a `Promise` which resolves with a `SignIn` object. Check the `secondFactorVerification` attribute for the status of the second factor verification process.

createMagicLinkFlow()

createMagicLinkFlow() => CreateMagicLinkFlowParams<SignInStartMagicLinkFlowParams, SignInResource>

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

Type	Description
CreateMagicLinkFlowReturn<SignInStartMagicLinkFlowParams, SignInResource>	This method returns two functions. One to start the magic link flow and the other to cancel waiting for the results.

authenticateWithRedirect(params)

authenticateWithRedirect(params: AuthenticateWithRedirectParams) => Promise<void>

Signs in users via OAuth. This is commonly known as Single Sign On (SSO), where an external account is used for verifying the user's identity.

Parameters

Type	Description
params	An object that specifies the verification strategy (one of the supported OAuth providers), the callback URL the OAuth provider should redirect to, as well as the URL that the user should be redirected to upon successful sign in.

Returns

Type	Description
Promise<void>	This method returns a `Promise` which doesn't resolve to any value.

authenticateWithMetamask()

authenticateWithMetamask() => Promise<SignInResource>

Starts a sign in flow that uses the Metamask browser extension to authenticate the user using their public wallet address.

Parameters

This methods does not accept any parameters.

Returns

Type	Description
Promise<SignInResource>	This method returns a `Promise` which resolves to the current `SignInResource`.

Interfaces

AttemptFirstFactorParams

Name	Type	Description
strategy	string	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. password: The verification will attempt to be completed with the user's password. web3_metamask_signature: The verification will attempt to be completed using the user's web3 wallet public address.
code?	string	The one-time code that was sent to the user as part of this verification step. Required when `strategy` is email_code or phone_code.
password?	string	The user's password string. Required when `strategy` is password.
signature?	string	Web3 wallet generated signature to be verified. This parameter is required only for web3 verification strategies.

AttemptSecondFactorParams

Name	Type	Description
strategy	string	The strategy to be used for second factor verification. Possible `strategy` values are: 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. totp: User must provide a 6-digit TOTP code generated by their authenticator app. The user will need to have created a TOTP secret beforehand so as to register it on their authentictor app via QR code, URI or even entering the secret itself.
code	string	For the `phone_code` strategy: The one-time code that was sent to the user as part of the prepareSecondFactor step. For the `totp` strategy: The TOTP generated by the user's authenticator app.

AuthenticateWithMetamaskParams

Name	Type	Description
redirectUrl?	string	The OAuth provider that will be used for singing in. Must be one of the supported `OAuthStrategy` values.

AuthenticateWithRedirectParams

Name	Type	Description
strategy	string	The OAuth provider that will be used for singing in. Must be one of the supported `OAuthStrategy` .
redirectUrl	string	The URL that the OAuth provider should redirect to, on successful authorization on their part.
redirectUrlComplete	string	The URL that the user will be redirected to, after successful authorization from the OAuth provider and Clerk sign in

PrepareFirstFactorParams

Name	Type	Description
strategy	string	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. oauth_<provider>: The user will be authenticated with their Social login account. See available OAuth Strategies.
emailAddressId?	string	Unique identifier for the user's email address that will receive an email message with the one-time authentication code. This parameter will work only when the email_code strategy is specified.
phoneNumberId?	string	Unique identifier for the user's phone number that will receive an SMS message with the one-time authentication code. This parameter will work only when the phone_code strategy is specified.
web3WalletId?	string	Unique identifier for the user's web3 wallet public address. This parameter will work only when the web3_metamask_signature strategy is specified.
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_)**.

PrepareSecondFactorParams

Name	Type	Description
strategy	string	The strategy used for verification. Each authentication identifier supports different verification strategies. Possible strategy values for second factor preparation are: phone_code: User will receive a one-time authentication code in their phone, via SMS. The SMS message will be sent to the user's phone number that was added when setting up 2FA. The `totp` strategy requires the user to have registered their secret on an authenticator app, which then periodically generates TOTPs, without the need for a preparation step.

Name	Type	Description
strategy	string	The strategy used for the authentication factor. 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. password: The user needs to provide their password in order to be authenticated. 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 login account. See available OAuth Strategies.
emailAddressId?	string	Unique identifier for the user's email address that will receive an email message with the one-time authentication code. This parameter will be present only for the email_code strategy.
phoneNumberId?	string	Unique identifier for the user's phone number that will receive an SMS message with the one-time authentication code. This parameter will be present only for the phone_code strategy.
web3WalletId?	string	Unique identifier for the user's web3 wallet public address. This parameter will work only when the web3_metamask_signature strategy is specified.
safeIdentifier?	string	The actual value of the user's email address (for email_code strategy) or phone number (phone_code strategy). This parameter will be present only for the email_code and phone_code strategies.
primary?	boolean	Denotes if the corresponding identification is user's primary
default?	boolean	Denotes if this is the default second factor

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. 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	Supply the user's password, if password strategy has been specified.
ticket	string	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_)**.

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.

UserData

Name	Type	Description
firstName?	string	The user's first name.
lastName?	string	The user's last name.
profileImageUrl?	string	The URL of the user's profile image.

VerificationResource

Name	Type	Description
status	string \| null	The verification status. Possible values are: unverified: The verification process has not been completed. verified: The verification process has completed successfully. transferable: The verification can be transferred as part of an external account verification process. failed: The verification process has been completed, but failed. expired: The verification is invalid because it wasn't completed in the allowed time.
strategy	string \| null	The verification strategy. Possible strategy values are: 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. password: The user needs to provide their password in order to be authenticated. web3_metamask_signature: The verification will attempt to be completed using the user's web3 wallet public address. oauth_<provider>: The user will be authenticated with their Social login account. See available OAuth Strategies. totp: The user needs to register their TOTP secret on an authenticator app via QR code, URI or simply copying the secret. The authenticticator app then periodically (every 30 seconds) generates TOTPs that the user can enter to attempt their second factor of authentication.
nonce	string \| null	A generated nonce that can be signed during Web3 authentication
attempts	string \| null	The number of attempts to complete the verification so far. Usually, a verification allows for maximum 3 attempts to be completed.
expireAt	Date \| null	The timestamp when the verification will expire and cease to be valid.
error	ClerkAPIError \| null	Any error that occurred during the verification process from the Clerk API.
externalVerificationRedirectURL	URL \| null	If this is a verification that is based on an external account (usually oauth_*), this is the URL that the user will be redirected to after the verification is completed.

Types

{ startMagicLinkFlow: (params: SignInStartMagicLinkFlowParams) => Promise<SignInResource>, cancelMagicLinkFlow: () => void }

Name	Description
startMagicLinkFlow	Function to start the magic link flow. It prepares a magic link verification and polls for the verification result. Accepts SignInStartMagicLinkFlowParams. Returns a `Promise` which resolves to a `SignInResource`.
cancelMagicLinkFlow	Function to cleanup the magic link flow. Stops waiting for verification results.

OAuthStrategy

Value	Description
oauth_facebook	Specify Facebook as the verification OAuth provider.
oauth_github	Specify Github as the verification OAuth provider.
oauth_google	Specify Google as the verification OAuth provider.
oauth_hubspot	Specify HubSpot as the verification OAuth provider.
oauth_tiktok	Specify TikTok as the verification OAuth provider.
oauth_gitlab	Specify GitLab as the verification OAuth provider.
oauth_discord	Specify Discord as the verification OAuth provider.
oauth_twitter	Specify Twitter as the verification OAuth provider.
oauth_twitch	Specify Twitch as the verification OAuth provider.
oauth_linkedin	Specify LinkedIn as the verification OAuth provider.
oauth_dropbox	Specify Dropbox as the verification OAuth provider.
oauth_bitbucket	Specify Bitbucket as the verification OAuth provider.
oauth_microsoft	Specify Microsoft as the verification OAuth provider.
oauth_notion	Specify Notion as the verification OAuth provider.

SignIn

The SignIn object contains the state of the current sign-in that the user has initiated.

Attributes

Methods

create(params)

prepareFirstFactor(params)

attemptFirstFactor(params)

prepareSecondFactor(params)

attemptSecondFactor(params)

createMagicLinkFlow()

authenticateWithRedirect(params)

authenticateWithMetamask()

Interfaces

AttemptFirstFactorParams

AttemptSecondFactorParams

AuthenticateWithMetamaskParams

AuthenticateWithRedirectParams

PrepareFirstFactorParams

PrepareSecondFactorParams

SignInFactor

SignInCreateParams

SignInStartMagicFlowParams

UserData

VerificationResource

Types

CreateMagicLinkFlowReturn<SignInStartMagicLinkFlowParams, SignInResource>

OAuthStrategy