Custom flows

A custom flow refers to a user flow created entirely from scratch using the Clerk API. If Clerk's prebuilt components don't meet your specific needs or if you require more control over the logic, you can rebuild the existing Clerk flows using the Clerk API.

Sign-up flow

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

Every SignUp 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 Clerk Dashboard. Once all requirements are met, the SignUp 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 progressive multi-step sign-up forms.

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.

Required fields

The SignUp object will show the state of the current sign-up in the status property.

You can also 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
requiredFields	All fields that must be collected before the SignUp converts into a User.
optionalFields	All fields that can be collected, but are not necessary to convert the SignUp into a User.
missing_fields	A subset of required_fields. It contains all fields that still need to be collected before a SignUp can be converted into a User. Note that this property will be updated dynamically. As you add more fields to the SignUp, they will be removed. Once this property is empty, your SignUp will automatically convert into a User.

Verified fields

Some fields of the SignUp, such as email_address and phone_number, must be verified before they are fully added to the SignUp. Similar to what happens with required fields, the SignUp contains the current state of all verified fields.

The following keys relate to the verification state of the SignUp:

Name	Description
unverifiedFields	A list of all User attributes that need to be verified and are pending verification. This is a list that gets updated dynamically. When verification for all required fields has been successfully completed, this value will become an empty array.
verifications	An object that describes the current state of verification for the SignUp. There are currently three different keys: email_address, phone_number, and external_account.

Sign-in flow

Sign-in's are initiated by creating a SignIn object on the current Client. The SignIn handles all the state and logic associated with a sign-in. If the sign-in is successfully authenticated, it will transform into an active session on the current Client.

The following steps outline the sign-in process:

1. Initiate the sign-in process by collecting the user's authentication information and passing the appropriate parameters to the create() method.
2. Prepare the first factor verification. Users must complete a first factor verification to prove their identity. This can be something like providing a password, an email link, a one-time code (OTP), a web3 wallet public address, or providing proof of their identity through an external social account (SSO/OAuth).
3. Attempt to complete the first factor verification.
4. Optionally, if you have enabled multi-factor for your application, you will need to prepare the second factor verification for users who have set up 2FA for their account.
5. Attempt to complete the second factor verification.
6. If 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.