If Clerk's prebuilt components don't meet your specific needs or if you require more control over the authentication flow, Clerk enables you to build fully custom sign-up and sign-in flows using the
useSignIn() React hooks.
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
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(opens in a new tab). 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
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.
SignUp object will show the state of the current sign-up. You can consult the
missing_fields keys for a hint on where things are and what you need to do next.
|All fields that must be collected before the
SignUp converts into a
|All fields that can be collected, but are not necessary to convert the
|A subset of
required_fields. It contains all fields that still need to be collected before a successful
SignUp. Note that the
missingFields will be updated dynamically. As you add more fields to the
SignUp, they will be removed from
missing_fields. Once it's empty, your
SignUp will automatically convert into a
The values of the collected fields are all accessible on the root of the
SignUp, under their corresponding keys;
phone_number are examples of such keys. Go to the
SignUp object documentiation for a list of all available attributes.
Some fields, such as
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 keys relative to verification are
|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.
|An object that describes the current state of verification for the
SignUp. There are currently three different keys:
Sign-in's are initiated by creating a
SignIn object on the current
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
Completing a sign-in
There are 3 main steps a user must perform in order to complete a sign-in.
The first step a user needs to make is to identify what account they'd like to sign in to. This is done with an identifier, which can either be an email address, a phone number, or a username.
Factor one verification
Once a user is identified, they need to prove their identity. This is the process of "authenticating" the user. There's a number of strategies a user can use to perform authentication with the most basic being the humble password. Other authentication strategies, like passwordless sign-in, can be explored in the sign-in options documentation.
Factor two verification (optional)
This step only applies to users that have turned on two-factor authentication, also known as multifactor authentication, for their user.
When one form of verification isn't enough, trust two! Forcing two different verification steps vastly increases the security of your account. The most common setup a user will have to protect their account is using a password as their first kind of verification and a
phone_code as their second kind of verification.
Last updated on September 19, 2023