Clerk logo

Clerk Docs

Ctrl + K
Go to clerk.dev

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

NameTypeDescription
statusstring

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.
requiredFieldsstring[]

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.

optionalFieldsstring[]

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.

missingFieldsstring[]

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.

unverifiedFieldsstring[]

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.

supportedExternalAccountsstring[]

An array of all the external accounts that are supported in the current sign-up, e.g. oauth_google, oauth_facebook, etc.

verificationsSignUpVerificationsResource

An object that contains information about all the verifications that are in-flight.

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

emailAddressstring | 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

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

web3Walletstring | null

The Web3 wallet public address supplied to the current sign-up. In Ethereum, the address is made up of 0x + 40 hexadecimal characters.

passwordEnabledboolean

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.

firstNamestring | 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

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

createdSessionIdstring | null

The identifier of the newly-created session. This attribute is populated only when the sign-up is complete.

createdUserIdstring | 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

NameDescription
params

SignUpParams

Returns

TypeDescription
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

NameDescription
params

SignUpParams

Returns

TypeDescription
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

NameDescription
params

SignUpVerificationParams

Returns

TypeDescription
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

NameDescription
params

SignUpVerificationAttemptParams

Returns

TypeDescription
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

TypeDescription
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

NameDescription
params

VerificationAttemptParams

Returns

TypeDescription
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() => 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

TypeDescription
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

TypeDescription
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

NameDescription
params

VerificationAttemptParams

Returns

TypeDescription
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

NameDescription
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

TypeDescription
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

NameTypeDescription
redirectUrlstring

Full URL or path to navigate after successful sign up.

Returns

This method has no return value

Interfaces

AuthenticateWithRedirectParams

NameTypeDescription
strategystring

The OAuth provider that will be used for singing in. Must be one of the supported OAuthStrategy values.

redirectUrlstring

The URL that the OAuth provider should redirect to, on successful authorization on their part.

redirectUrlCompletestring

The URL that the user will be redirected to, after successful authorization from the OAuth provider and Clerk sign in

SignUpParams

NameTypeDescription
firstNamestring | 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.

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

passwordstring | null

The user's password.
This option is available only if password-based authentication is selected.
Please check the instance settings for more information.

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

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

web3Walletstring | null

The user's Web3 wallet public address. In Ethereum, the address is made up of 0x + 40 hexadecimal characters.

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

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

SignUpVerificationsResource

NameDescription
emailAddress

SignUpVerificationResource

phoneNumber

SignUpVerificationResource

web3Wallet

SignUpVerificationResource

SignUpVerificationResource

NameTypeDescription
statusstring | null

The verification status.

nextActionstring

Specifies the action that you could do next in order to complete this verification.

supportedStrategiesstring[]

An array of all strategies supported for this resource.

strategystring | 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.
attemptsnumber | null

The number of attempts to complete the verification so far. Usually, a verification allows for maximum 3 attempts to be completed.

expireAtDate | null

The timestamp when the verification will expire and cease to be valid.

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

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

SignUpVerificationAttemptParams

NameTypeDescription
strategySignUpVerificationStrategy

SignUpVerificationStrategy

codestring

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.

NameTypeDescription
redirectUrlstring

The URL to be redirected to after the magic link verification is prepared.

VerificationAttemptParams

NameTypeDescription
codestring

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 }

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

SignUpVerificationStrategy

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

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.

Was this helpful?

Clerk © 2022