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(opens in a new tab) endpoint from the Backend API.

Progressive Sign Up involves changes in the responses of the Frontend API(opens in a new tab). 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 the SignUp 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

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

The Progressive Sign Up flow can be toggled on via an instance setting, using the Instance Settings(opens in a new tab) endpoint in Backend API. In the future, this setting 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.

Last updated on January 31, 2024