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:
|
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 |
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 |
userData | UserDate | null | An object containing information about the user of the current sign in. |
createdSessionId | string | null | The identifier of the session that was created upon completion of the current sign-in. |
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 |
Returns
Type | Description |
---|---|
Promise<SignInResource> | This method returns a |
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 |
Returns
Type | Description |
---|---|
Promise<SignInResource> | This method returns a |
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 |
Returns
Type | Description |
---|---|
Promise<SignInResource> | This method returns a |
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 |
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 |
Returns
Type | Description |
---|---|
Promise<SignInResource> | This method returns a |
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 |
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 |
Interfaces
AttemptFirstFactorParams
Name | Type | Description |
---|---|---|
strategy | string | The
|
code? | string | The one-time code that was sent to the user as part of this verification step. Required when |
password? | string | The user's password string. Required when |
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
|
code | string |
|
AuthenticateWithMetamaskParams
Name | Type | Description |
---|---|---|
redirectUrl? | string | The OAuth provider that will be used for singing in. Must be one of the supported |
AuthenticateWithRedirectParams
Name | Type | Description |
---|---|---|
strategy | string | The OAuth provider that will be used for singing in. Must be one of the supported |
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
|
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:
The |
SignInFactor
Name | Type | Description |
---|---|---|
strategy | string | The strategy used for the authentication factor. The
|
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 |
SignInCreateParams
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
|
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_*). |
SignInStartMagicFlowParams
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:
|
strategy | string | null | The verification strategy. Possible strategy values are:
|
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
CreateMagicLinkFlowReturn<SignInStartMagicLinkFlowParams, SignInResource>
{ 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 |
cancelMagicLinkFlow | Function to cleanup the magic link flow. Stops waiting for verification results. |
OAuthStrategy
oauth_facebook | oauth_github | oauth_google | oauth_hubspot | oauth_tiktok | oauth_gitlab | oauth_discord | oauth_twitter | oauth_twitch | oauth_linkedin | oauth_dropbox | oauth_bitbucket | oauth_microsoft | oauth_notion
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. |