Skip to Content
Clerk logo

Clerk Docs

Ctrl + K
Go to clerk.com

SignUp

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.

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.

Properties

NameTypeDescription
idstring | undefinedThe unique identifier of the current sign-up.
status'missing_requirements' | 'complete' | 'abandoned' | nullThe status of the current sign-up.
The following values are supported:
  • 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.
verificationsSignUpVerificationsAn object that contains information about all the verifications that are in-flight.
usernamestring | nullThe username supplied to the current sign-up. This attribute is available only if usernames are enabled. Check the available instance settings in your Clerk Dashboard for more information.
emailAddressstring | nullThe 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 | nullThe 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 | nullThe Web3 wallet public address supplied to the current sign-up. In Ethereum(opens in a new tab), the address is made up of 0x + 40 hexadecimal characters.
hasPasswordbooleanThe 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 | nullThe 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 | nullThe 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} | nullMetadata 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 | nullThe identifier of the newly-created session. This attribute is populated only when the sign-up is complete.
createdUserIdstring | nullThe identifier of the newly-created user. This attribute is populated only when the sign-up is complete.
abandonAtnumber | nullThe epoch numerical time when the sign-up was abandoned by the user.

Methods

create()

function create(params: SignUpCreateParams): 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. Clerk's sign-up process provides great flexibility and allows users to easily create multi-step sign-up flows.

SignUpCreateParams

NameTypeDescription
firstNamestring | nullThe 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 | nullThe 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 | nullThe user's password. This option is available only if password-based authentication is selected. Please check the instance settings for more information.
genderstring | nullThe user's gender. This option is available only if gender is selected in personal information. Please check the instance settings for more information.
emailAddressstring | nullThe 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 | nullThe 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 | nullThe user's Web3 wallet public address. In Ethereum(opens in a new tab), the address is made up of 0x + 40 hexadecimal characters.
usernamestring | nullThe user's username. This option is available only if usernames are enabled. Please check the instance settings for more information.
unsafeMetadata{[string]: any} | nullMetadata 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.
strategy'oauth_<provider>' | 'saml' | 'ticket'The strategy to use for the sign-up flow.
The following strategies are supported:
  • oauth_<provider>: The user will be authenticated with their Social login account. See available OAuth Strategies.
  • saml: The user will be authenticated with SAML.
  • ticket: The user will be authenticated via the ticket or token generated from the Backend API.
redirectUrlstringThe redirect URL after the sign-up flow has completed.
actionCompleteRedirectUrl?stringThe URL that the user will be redirected to, after successful authorization from the OAuth provider and Clerk sign in. This parameter is required only if strategy is set to an OAuth strategy like oauth_<provider>, or set to saml.
ticketstringProvide the ticket or token generated from the Backend API. This parameter is required only if strategy is set to ticket.
transferbooleanTransfer the user to a dedicated sign-up for an OAuth flow.

update()

function update(params: SignUpUpdateParams): 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.

SignUpUpdateParams

SignUpUpdateParams is a mirror of SignUpCreateParams with the same fields and types.

function createMagicLinkFlow(): { startMagicLinkFlow: (params: StartMagicLinkFlowParams) => Promise<SignUp>; cancelMagicLinkFlow: () => void; };

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

createMagicLinkFlow returns an object with two functions:

NameTypeDescription
startMagicLinkFlow(params: StartMagicLinkFlowParams) => Promise<SignUp>Function to start the magic link flow. It prepares a magic link verification and polls for the verification result.
NameTypeDescription
redirectUrlstringThe magic link target URL. Users will be redirected here once they click the magic link from their email.

Additional methods

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

Authenticate with

Verification

Email verification

Phone verification

Web3 verification

Last updated on February 12, 2024

What did you think of this content?

Clerk © 2024