Skip to main content
Docs

SignUp

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

The following steps outline the sign-up process:

  1. Initiate the sign-up process by collecting the user's authentication information and passing the appropriate parameters to the create() method.
  2. Prepare the verification.
  3. Attempt to complete the verification.
  4. If the verification is successful, set the newly created session as the active session by passing the SignIn.createdSessionId to the setActive() method on the Clerk object.

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:

    • complete: The user has been created and the custom flow can proceed to setActive() to create session.
    • missing_requirements: A requirement is unverified or missing from the Email, Phone, Username settings. For example, in the Clerk Dashboard, the Password setting is required but a password wasn't provided in the custom flow.
    • abandoned: The sign-up has been inactive for over 24 hours.
  • 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. Only supported if username is enabled in the instance settings.

  • Name
    emailAddress
    Type
    string | null
    Description

    The email address supplied to the current sign-up. Only supported if email address is enabled in the instance settings.

  • Name
    phoneNumber
    Type
    string | null
    Description

    The user's phone number in E.164 format. Only supported if phone number is enabled in the instance settings.

  • Name
    web3Wallet
    Type
    string | null
    Description

    The Web3 wallet address, made up of 0x + 40 hexadecimal characters. Only supported if Web3 authentication is enabled in the instance settings.

  • Name
    hasPassword
    Type
    boolean
    Description

    The value of this attribute is true if a password was supplied to the current sign-up. Only supported if password is enabled in the instance settings.

  • Name
    firstName
    Type
    string | null
    Description

    The first name supplied to the current sign-up. Only supported if name is enabled in the instance settings.

  • Name
    lastName
    Type
    string | null
    Description

    The last name supplied to the current sign-up. Only supported if name is enabled in the instance settings.

  • Name
    unsafeMetadata
    Type
    SignUpUnsafeMetadata
    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()

Returns a new SignUp object based on the params you pass to it, stores the sign-up lifecycle state in the status property, and deactivates any existing sign-up process the client may already have in progress. Use this method to initiate a new sign-up process.

What you must pass to params depends on which sign-up options you have enabled in your Clerk application instance.

Optionally, you can complete the sign-up process in one step if you supply the required fields to create(). Otherwise, Clerk's sign-up process provides great flexibility and allows users to easily create multi-step sign-up flows.

Warning

Once the sign-up process is complete, pass the createdSessionId to the setActive() method on the Clerk object. This will set the newly created session as the active session.

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

SignUpCreateParams

  • Name
    strategy
    Type
    'oauth_<provider>' | 'saml' | 'enterprise_sso' | 'ticket' | 'google_one_tap'
    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 connection account. See a list of supported values for <provider>.
    • 'saml' (deprecated): Deprecated in favor of 'enterprise_sso'. The user will be authenticated with their SAML account.
    • 'enterprise_sso': The user will be authenticated either through SAML or OIDC depending on the configuration of their enterprise SSO account.
    • 'ticket': The user will be authenticated via the ticket or token generated from the Backend API.
    • 'google_one_tap': The user will be authenticated with the Google One Tap UI. It's recommended to use authenticateWithGoogleOneTap() instead, as it will also set the user's current session as active for you.
  • Name
    firstName
    Type
    string | null
    Description

    The user's first name. Only supported if name is enabled.

  • Name
    lastName
    Type
    string | null
    Description

    The user's last name. Only supported if name is enabled.

  • Name
    password
    Type
    string | null
    Description

    The user's password. Only supported if password is enabled.

  • Name
    emailAddress
    Type
    string | null
    Description

    The user's email address. Only supported if email address is enabled. Keep in mind that the email address requires an extra verification process.

  • Name
    phoneNumber
    Type
    string | null
    Description

    The user's phone number in E.164 format. Only supported if phone number is enabled. Keep in mind that the phone number requires an extra verification process.

  • Name
    web3Wallet
    Type
    string | null
    Description

    Required if Web3 authentication is enabled. The Web3 wallet address, made up of 0x + 40 hexadecimal characters.

  • Name
    username
    Type
    string | null
    Description

    The user's username. Only supported if usernames are enabled.

  • Name
    unsafeMetadata
    Type
    SignUpUnsafeMetadata
    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
    redirectUrl
    Type
    string
    Description

    If strategy is set to 'oauth_<provider>' or 'enterprise_sso', this specifies full URL or path that the OAuth provider should redirect to after successful authorization on their part. Typically, this will be a simple /sso-callback route that either calls Clerk.handleRedirectCallback or mounts the <AuthenticateWithRedirectCallback /> component. See the custom flow for implementation details.

    If strategy is set to 'email_link', this specifies the URL that the user will be redirected to when they visit the email link. See the custom flow for implementation details.

  • Name
    actionCompleteRedirectUrl
    Type
    string
    Description

    Optional if strategy is set to 'oauth_<provider>' or 'enterprise_sso'. The URL that the user will be redirected to after successful authorization from the OAuth provider and Clerk sign-in.

  • Name
    ticket
    Type
    string
    Description

    Required if strategy is set to 'ticket'. The ticket or token generated from the Backend API.

  • Name
    transfer
    Type
    boolean
    Description

    When set to true, the SignUp will attempt to retrieve information from the active SignIn instance and use it to complete the sign-up process. This is useful when you want to seamlessly transition a user from a sign-in attempt to a sign-up attempt.

  • Name
    legalAccepted
    Type
    boolean
    Description

    A boolean indicating whether the user has agreed to the legal compliance documents.

  • Name
    oidcPrompt
    Type
    string
    Description

    Optional if strategy is set to 'oauth_<provider>' or 'enterprise_sso'. The value to pass to the OIDC prompt parameter in the generated OAuth redirect URL.

  • Name
    oidcLoginHint
    Type
    string
    Description

    Optional if strategy is set to 'oauth_<provider>' or 'enterprise_sso'. The value to pass to the OIDC login_hint parameter in the generated OAuth redirect URL.

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.

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 URL that the user will be redirected to when they visit the email link.

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

Example

For examples of how to access the SignUp object and use the associated methods, see the custom flow guides.

Feedback

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

Last updated on