SignUp

The SignUp object contains the state of the current sign-up that the user has initiated.

Overview

The SignUp object holds the state of the current sign up and provides helper methods to navigate and complete the sign up flow. Once a sign up is complete, a new user is created.

There are two important steps that need to be done in order for a sign up to be completed:

Supply all the required fields. The required fields depend on your instance settings.
Verify contact information. Some of the supplied fields need extra verification. These are the email address and phone number.

The above steps can be split into smaller actions (e.g. you don't have to supply all the required fields at once) and can done in any order. This provides great flexibility and supports even the most complicated sign up flows. The SignUp object provides a number of helper methods to achieve the above.

Also, the attributes of the SignUp object can basically be grouped into three categories:

Those that contain information regarding the sign-up flow and what is missing in order for the sign-up to complete. For more information on these, check our detailed sign-up flow guide.
Those that hold the different values that we supply to the sign-up. Examples of these are username, emailAddress, firstName, etc.
Those that contain references to the created resources once the sign-up is complete, i.e. createdSessionId and createdUserId.

Attributes

Name	Type	Description
status	string	The status of the current sign-up. It can take the following values: missing_requirements: There are required fields that are either missing or they are unverified. complete: All the required fields have been supplied and verified, so the sign-up is complete and a new user and a session have been created. abandoned: The sign-up has been inactive for a long period of time, thus it's considered as abandoned and need to start over.
requiredFields	string[]	An array of all the required fields that need to be supplied and verified in order for this sign-up to be marked as complete and converted into a user.
optionalFields	string[]	An array of all the fields that can be supplied to the sign-up, but their absence does not prevent the sign-up from being marked as complete.
missingFields	string[]	An array of all the fields whose values are not supplied yet but they are mandatory in order for a sign-up to be marked as complete.
unverifiedFields	string[]	An array of all the fields whose values have been supplied, but they need additional verification in order for them to be accepted. Examples of such fields are `emailAddress` and `phoneNumber`.
supportedExternalAccounts	string[]	An array of all the external accounts that are supported in the current sign-up, e.g. `oauth_google`, `oauth_faceboo`k, etc.
verifications	SignUpVerificationsResource	An object that contains information about all the verifications that are in-flight.
username	string \| null	The username supplied to the current sign-up. This attribute is available only if usernames are enabled. Check the available instance settings for more information.
emailAddress	string \| null	The email address supplied to the current sign-up. This attribute is available only if the selected contact information includes email address. Check the available instance settings for more information
phoneNumber	string \| null	The phone number supplied to the current sign-up. This attribute is available only if the selected contact information includes phone number. Check the available instance settings for more information.
web3Wallet	string \| null	The Web3 wallet public address supplied to the current sign-up. In Ethereum, the address is made up of `0x` + `40 hexadecimal characters`.
passwordEnabled	boolean	The value of this attribute is true if a password was supplied to the current sign-up. This attribute is available only if password-based authentication is enabled. Check the available instance settings for more information.
firstName	string \| null	The first name supplied to the current sign-up. This attribute is available only if name is enabled in personal information. Check the available for more information. lastName
lastName	string \| null	The last name supplied to the current sign-up. This attribute is available only if name is enabled in personal information. Check the available instance settings for more information.
unsafeMetadata	{[string]: any} \| null	Metadata that can be read and set from the frontend. Once the sign up is complete, the value of this field will be automatically copied to the newly created user's unsafe metadata. One common use case for this attribute is to use it to implement custom fields that can be collected during sign up and will automatically be attached to the created User object.
createdSessionId	string \| null	The identifier of the newly-created session. This attribute is populated only when the sign-up is complete.
createdUserId	string \| null	The identifier of the newly-created user. This attribute is populated only when the sign-up is complete.

Methods

create(params)

create(params: SignUpParams) => Promise<SignUpResource>

This method initiates a new sign-up flow. It creates a new SignUp object and de-activates any existing SignUp that the client might already had in progress.

The form of the given params depends on the configuration of the instance. Choices on the instance settings affect which options are available to use.

The create method will return a promise of the new SignUp object. This sign up might be complete if you supply the required fields in one go. However, this is not mandatory. Our sign-up process provides great flexibility and allows users to easily create multi-step sign-up flows.

Parameters

Name	Description
params	SignUpParams

Returns

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

update(params)

update(params: SignUpParams) => Promise<SignUpResource>This method is used to update the current sign up.

As with create, the form of the given params depends on the configuration of the instance.

Parameters

Name	Description
params	SignUpParams

Returns

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

prepareVerification(strategy)

prepareVerification(strategy: SignUpVerificationStrategy) => Promise<SignUpResource>

The prepareVerification is used to initiate the verification process for a field that requires it. As mentioned above, there are two fields that need to be verified:

emailAddress: The email address can be verified via an email code. This is a one-time code that is sent to the email already provided to the SignUp object. The prepareVerification sends this email.
phoneNumber: The phone number can be verified via a phone code. This is a one-time code that is sent via an SMS to the phone already provided to the SignUp object. The prepareVerification sends this SMS.

Parameters

Name	Description
params	SignUpVerificationParams

Returns

Type	Description
Promise<SignUpResource>	This method returns a `Promise` which resolves with a `SignUp` object.

attemptVerification(params)

attemptVerification(params: SignUpVerificationAttemptParams) => Promise<SignUpResource>

Attempts to complete the in-flight verification process that corresponds to the given strategy. In order to use this method, you should first initiate a verification process by calling SignUp.prepareVerification.

Depending on the strategy, the method parameters could differ.

Parameter

Name	Description
params	SignUpVerificationAttemptParams

Returns

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

prepareEmailAddressVerification()

prepareEmailAddressVerification() => Promise<SignUpResource>

Helper method that allows you to initiate a verification process for an email address. It basically sends a one-time code to the email address already supplied to the current sign up.

This is equivalent to calling SignUp.prepareVerification("email_code").

Returns

Type	Description
Promise<SignUpResource>	This method returns a `Promise` which resolves with a `SignUp` object.

attemptEmailAddressVerification(params)

attemptEmailAddressVerification(params: VerificationAttemptParams) => Promise<SignUpResource>

Helper method that attempts to complete the verification process for an email address. It basically verifies that the supplied code is the same as the one-time code that was sent to the email address during the prepare verification phase.

This is equivalent to calling SignUp.attemptVerification({strategy: "email_code", ...params}).

Parameter

Name	Description
params	VerificationAttemptParams

Returns

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

createMagicLinkFlow()

createMagicLinkFlow() => CreateMagicLinkFlowParams<StartMagicLinkFlowParams, SignUpResource>

Sets up a sign up 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 }) => Promise<SignUpResource>.

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<StartMagicLinkFlowParams, SignUpResource>	This method returns two functions. One to start the magic link flow and the other to cancel waiting for the results.

preparePhoneNumberVerification()

preparePhoneNumberVerification() => Promise<SignUpResource>

Helper method that allows you to initiate a verification process for a phone number. It basically sends a one-time code to the phone number already supplied to the current sign up.

This is equivalent to calling SignUp.prepareVerification("phone_code").

Returns

Type	Description
Promise<SignUpResource>	This method returns a `Promise` which resolves with a `SignUp` object.

attemptPhoneNumberVerification(params)

attemptPhoneNumberVerification(params: VerificationAttemptParams) => Promise<SignUpResource>

Helper method that attempts to complete the verification process for a phone number. It basically verifies that the supplied code is the same as the one-time code that was sent to the phone number during the prepare verification phase.

This is equivalent to calling SignUp.attemptVerification({strategy: "phone_code", ...params}).

Parameter

Name	Description
params	VerificationAttemptParams

Returns

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

prepareWeb3WalletVerification()

prepareWeb3WalletVerification() => Promise<SignUpResource>

Helper method that allows you to initiate a verification process for a web3 wallet public address. It sends the public address to the server and expects a nonce that will need to be signed.

This is equivalent to calling SignUp.prepareVerification("web3_metamask_signature").

attemptWeb3WalletVerification()

attemptPhoneNumberVerification() => Promise<SignUpResource>

Helper method that attempts to complete the verification process for a web3 wallet public address. It basically verifies that the supplied code is the same as the one-time code that was sent to the phone number during the prepare verification phase.

This is equivalent to calling SignUp.attemptVerification({strategy: "web3_metamask_signature", signature: "..." }).

authenticateWithRedirect(params)

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

Signs up users via OAuth, where an external account provider is used to verify the user's identity and provide certain information about the user.

Parameter

Name	Description
params	AuthenticateWithRedirectParams 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(params)

authenticateWithMetamask(params: AuthenticateWithMetamaskParams) => void

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

Parameter

Name	Type	Description
redirectUrl	string	Full URL or path to navigate after successful sign up.

Returns

This method has no return value

Interfaces

AuthenticateWithRedirectParams

Name	Type	Description
strategy	string	The OAuth provider that will be used for singing in. Must be one of the supported OAuthStrategy values.
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

Name	Type	Description
firstName	string \| null	The user's first name. This option is available only if name is selected in personal information. Please check the instance settings for more information.
lastName	string \| null	The user's last name. This option is available only if name is selected in personal information. Please check the instance settings for more information.
password	string \| null	The user's password. This option is available only if password-based authentication is selected. Please check the instance settings for more information.
emailAddress	string \| null	The user's email address. This option is available only if email address is selected in contact information. Keep in mind that the email address requires an extra verification process. Please check the instance settings for more information.
phoneNumber	string \| null	The user's phone number. This option is available only if phone number is selected in contact information. Keep in mind that the phone number requires an extra verification process. Please check the instance settings for more information.
web3Wallet	string \| null	The user's Web3 wallet public address. In Ethereum, the address is made up of `0x` + `40 hexadecimal characters`.
username	string \| null	The user's username. This option is available only if usernames are enabled. Please check the instance settings for more information.
unsafeMetadata	{[string]: any} \| null	Metadata that can be read and set from the frontend. Once the sign up is complete, the value of this field will be automatically copied to the newly created user's unsafe metadata. One common use case for this attribute is to use it to implement custom fields that can be collected during sign up and will automatically be attached to the created User object.
invitationToken	string \| null	It represents a token that was generated as part of an invitation creation. Using this token, you can auto-verify the email address that this invitation was sent to without any additional steps. For more information about how invitations work, refer to our Invitations guide.

Name	Description
emailAddress	SignUpVerificationResource
phoneNumber	SignUpVerificationResource
web3Wallet	SignUpVerificationResource

Name	Type	Description
status	string \| null	The verification status.
nextAction	string	Specifies the action that you could do next in order to complete this verification.
supportedStrategies	string[]	An array of all strategies supported for this resource.
strategy	string \| null	The verification strategy. Possible strategy values are: email_code: User will receive a one-time authentication code via email. phone_code: User will receive a one-time authentication code in their phone, via SMS.
attempts	number \| 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.
unsafeMetadata	{[string]: any} \| null	Metadata that can be read and set from the frontend. Once the sign up is complete, the value of this field will be automatically copied to the newly created user's unsafe metadata. One common use case for this attribute is to use it to implement custom fields that can be collected during sign up and will automatically be attached to the created User object.
invitationToken	string \| null	It represents a token that was generated as part of an invitation creation. Using this token, you can auto-verify the email address that this invitation was sent to without any additional steps. For more information about how invitations work, refer to our Invitations guide.

Name	Type	Description
strategy	SignUpVerificationStrategy	SignUpVerificationStrategy
code	string	This property is applicable for strategies `email_code` and `phone_code`. This represents the one-time code that was sent to either the email address or the phone number during the SignUp.prepareVerification step.

StartMagicLinkFlowParams

Name	Type	Description
redirectUrl	string	The URL to be redirected to after the magic link verification is prepared.

VerificationAttemptParams

Name	Type	Description
code	string	This property is applicable for strategies `email_code` and `phone_code`. This represents the one-time code that was sent to either the email address or the phone number during the SignUp.prepareVerification step.

Types

{ startMagicLinkFlow: (params: StartMagicLinkFlowParams) => Promise<SignUpResource>, cancelMagicLinkFlow: () => void }

Name	Description
startMagicLinkFlow	Function that starts the magic link flow. It prepares a magic link verification and polls for the verification result. Accepts StartMagicLinkFlowParams. Returns a Promise which resolves to a SignUpResource. You can check the SignUpResource verifications for the verification result.
cancelMagicLinkFlow	Function to cleanup the magic link flow. Stops waiting for verification results.

Value	Description
email_link	Specify email code as the verification strategy. This applies only to email addresses and is a one-time code sent to that email address.
email_code	Specify email code as the verification strategy. This applies only to email addresses and is a one-time code sent to that email address.
phone_code	Specify phone code as the verification strategy. This applies only to phone number and is a one-time code sent to that phone number via SMS.
web3_metamask_signature	The verification will attempt to be completed using the user's web3 wallet public address.

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.

SignUp

The SignUp object contains the state of the current sign-up that the user has initiated.

Attributes

Methods

create(params)

update(params)

prepareVerification(strategy)

attemptVerification(params)

prepareEmailAddressVerification()

attemptEmailAddressVerification(params)

createMagicLinkFlow()

preparePhoneNumberVerification()

attemptPhoneNumberVerification(params)

prepareWeb3WalletVerification()

attemptWeb3WalletVerification()

authenticateWithRedirect(params)

authenticateWithMetamask(params)

Interfaces

AuthenticateWithRedirectParams

SignUpParams

SignUpVerificationsResource

SignUpVerificationResource

SignUpVerificationAttemptParams

StartMagicLinkFlowParams

VerificationAttemptParams

Types

CreateMagicLinkFlowReturn<StartMagicLinkParams, SignUpResource>

SignUpVerificationStrategy

OAuthStrategy