Clerk logo

Clerk Docs

Ctrl + K
Go to clerk.devGet API keys

Sign up flow

Detailed documentation on how the sign up process works.

Overview

Clerk provides a flexible way to build sign up flows in your application. You can use a single Sign Up object to gather information, verify their email address or phone number, add OAuth accounts, and finally, convert them into a User.

Every Sign Up has a set of requirements it must meet before it is turned into a User. These requirements are defined by the instance settings you selected in the dashboard. Once all requirements are met, the Sign Up will turn into a new User, and an active session for that User will be created on the current Client.

Don't worry about collecting all the required fields at once and passing them to a single request. The API is designed to accommodate a progressive sign up flow, often corresponding to multi-step sign up forms.

Required fields

The Sign Up will show the current state of requirement collection. You can consult the required_fields, optional_fields and missing_fields keys for a hint on where things are and what you need to do next.

Name Description
required_fields All fields that must be collected before the Sign Up converts into a User.
optional_fields All fields that can be collected, but are not necessary to convert the Sign Up.
missing_fields A subset of required_fields. It contains all fields that still need to be collected before a successful Sign Up. Note that the missing_fields will be updated dynamically. As you add more fields to the Sign Up, they will be removed from missing_fields. Once it's empty, your Sign Up will automatically convert into a User.

The values of the collected fields are all accessible on the root of the Sign Up, under their corresponding keys; email_address and phone_number are examples of such keys.

Verified fields

Some fields, such as email_address and phone_number , must be verified before it is fully added to the Sign Up. Similar to what happens with required fields, the Sign Up contains the current state of all verified fields. The keys relative to verification are unverified_fields and verifications.

Name Description
unverified_fields a list of all User. attributes that need to be verified and are pending verification. This is a list that gets updated dynamically, eventually becoming an empty array, when verification for all required fields has been successfully completed.
verifications an object that describes the current state of verification for the Sign Up.. There are currently three different keys nested in there; email_address, phone_number and external_account.

Progressive Sign Up

Progressive Sign Up is a new Sign Up flow introduced in Q2 2022, that aims to improve upon the previous implementation by handling more scenarios and adhering more strictly to the authentication settings of the instance. Additionally, it allows Web3 authentication to be used together with the regular authentication settings.

It can be enabled using the Instance Settings endpoint from the Backend API.

Progressive Sign Up involves changes in the responses of the Frontend API. That said, there are no structural changes in the keys of the response payloads or any new types introduced. The changes only apply to some existing fields of Sign Up object, namely missing_fields, unverified_fields and status. The possible values of those fields also haven not changed - what changes is when each of those values is returned.

What’s changed

On a high level, Progressive Sign Up contains the following changes:

  • When someone was signing up using a Social provider (OAuth), even if the ‘name’ and ‘phone’ were marked as ‘required’, they were ignored and the user would sign up successfully but have an empty name and phone number. Now they have to be collected before the sign-up can complete.
  • When someone was signing up using a Social provider (OAuth) and the provider did not provide a verified email for the user, the process would result in an error. Now, this case will be handled gracefully: email has to be provided and verified, before the sign-up can complete.
  • Web3 could not be used in combination with any of the regular settings (i.e. email, name, phone number, passwords). Progressive Sign Up adds support for using Web3 together with these.
  • Emails and phones could not be marked as required/optional. In Progressive Sign Up they can, and the setting will be honored during Sign Up flows.

On a technical level, what changes is that the values of the following fields will more accurately represent the current state of the sign-up, adhering to the instance’s authentication requirements. This practically means:

  • sign_up.status may now be set to missing_requirements after a successful OAuth or Web3 flow
  • sign_up.missing_fields may be non-empty after a successful OAuth or Web3 flow
  • sign_up.unverified_fields may be non-empty after a successful OAuth or Web3 flow

Migrate to Progressive Sign Up

If your application was created after 7 June 2022, your 're already using Progressive Sign Up.

Before you enable Progressive Sign Up, make sure you’re on Clerk.js version 3.13.2 or later.

Progressive Sign Up can be toggled on via an instance setting, using the Instance Settings endpoint in Backend API. In the future it will be exposed as a Dashboard toggle as well.

If you're using the pre-built UI components, there are no changes required on your behalf.

If you're implementing a custom flow, you should cater for the case in which, after a successful OAuth or Web3 flow, the sign-up might still be in a pending state. This essentially means that you should peek into sign_up.status, sign_up.missing_fields and sign_up.unverified_fields and act accordingly.

For more information on how these fields behave, refer to Sign Up flow.

Conclusion

We encourage you to try the new sign up flow out and we are more than happy to assist you if you encounter any issues.

Your feedback is extremely important to us - please reach out via the following communication channels, in case you have questions, suggestions or issues.

Was this helpful?

Clerk © 2022