Docs

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

  • Name
    id
    Type
    string | undefined
    Description

    The unique identifier of the current sign-up.

  • Name
    status
    Type
    'missing_requirements' | 'complete' | 'abandoned' | null
    Description

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

  • Name
    requiredFields
    Type
    string[]
    Description

    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.

  • Name
    optionalFields
    Type
    string[]
    Description

    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.

  • Name
    missingFields
    Type
    string[]
    Description

    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.

  • Name
    unverifiedFields
    Type
    string[]
    Description

    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.

  • Name
    verifications
    Type
    SignUpVerifications
    Description

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

  • Name
    username
    Type
    string | null
    Description

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

  • Name
    emailAddress
    Type
    string | null
    Description

    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.

  • Name
    phoneNumber
    Type
    string | null
    Description

    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.

  • Name
    web3Wallet
    Type
    string | null
    Description

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

  • Name
    hasPassword
    Type
    boolean
    Description

    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.

  • Name
    firstName
    Type
    string | null
    Description

    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

  • Name
    lastName
    Type
    string | null
    Description

    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.

  • Name
    unsafeMetadata
    Type
    {[string]: any} | null
    Description

    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.

  • Name
    createdSessionId
    Type
    string | null
    Description

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

  • Name
    createdUserId
    Type
    string | null
    Description

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

  • Name
    abandonAt
    Type
    number | null
    Description

    The epoch numerical time when the sign-up was abandoned by the user.

Methods

create()

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.

function create(params: SignUpCreateParams): Promise<SignUpResource>;

SignUpCreateParams

  • Name
    firstName
    Type
    string | null
    Description

    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.

  • Name
    lastName
    Type
    string | null
    Description

    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.

  • Name
    password
    Type
    string | null
    Description

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

  • Name
    gender
    Type
    string | null
    Description

    The user's gender. This option is available only if gender is selected in personal information. Please check the instance settings for more information.

  • Name
    emailAddress
    Type
    string | null
    Description

    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.

  • Name
    phoneNumber
    Type
    string | null
    Description

    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.

  • Name
    web3Wallet
    Type
    string | null
    Description

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

  • Name
    username
    Type
    string | null
    Description

    The user's username. This option is available only if usernames are enabled. Please check the instance settings for more information.

  • Name
    unsafeMetadata
    Type
    {[string]: any} | null
    Description

    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.

  • Name
    strategy
    Type
    'oauth_<provider>' | 'saml' | 'ticket'
    Description

    The strategy to use for the sign-up flow.
    The following strategies are supported:

    • oauth_<provider>: The user will be authenticated with their social sign-in account. See available OAuth providers.
    • saml: The user will be authenticated with SAML.
    • ticket: The user will be authenticated via the ticket or token generated from the Backend API.

  • Name
    redirectUrl
    Type
    string
    Description

    The redirect URL after the sign-up flow has completed.

  • Name
    actionCompleteRedirectUrl?
    Type
    string
    Description

    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 if strategy is set to an OAuth strategy like oauth_<provider>, or set to saml.

  • Name
    ticket
    Type
    string
    Description

    Provide the ticket or token generated from the Backend API. This parameter is required only if strategy is set to ticket.

  • Name
    transfer
    Type
    boolean
    Description

    Transfer the user to a dedicated sign-up for an OAuth flow.

create() returns

TypeDescription
Promise<SignUpResource>A Promise which resolves to the current SignUp.

update()

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.

function update(params: SignUpUpdateParams): Promise<SignUpResource>;

SignUpUpdateParams

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

update() returns

TypeDescription
Promise<SignUpResource>This method returns a Promise which resolves to the current SignUp.
function createEmailLinkFlow(): {
  startEmailLinkFlow: (params: StartEmailLinkFlowParams) => Promise<SignUp>;
  cancelEmailLinkFlow: () => void;
};

Sets up a sign-up with email link flow. Calling createEmailLinkFlow() will return two functions.

The first function is async and starts the email link flow, preparing an email link verification. It sends the email link email and starts polling for verification results. The signature is startEmailLinkFlow({ 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 cancelEmailLinkFlow() => void.

function createEmailLinkFlow(): {
  startEmailLinkFlow: (params: StartEmailLinkFlowParams) => Promise<SignUpResource>;
  cancelEmailLinkFlow: () => void;
};

createEmailLinkFlow returns an object with two functions:

  • Name
    startEmailLinkFlow
    Type
    (params: StartEmailLinkFlowParams) => Promise<SignUp>
    Description

    Function to start the email link flow. It prepares an email link verification and polls for the verification result.

  • Name
    redirectUrl
    Type
    string
    Description

    The email link target URL. Users will be redirected here once they click the email 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

Feedback

What did you think of this content?
Edit this page on GitHub