Custom flows
A custom flow refers to a user flow created entirely from scratch using the Clerk API. If 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.
How authentication flows work in Clerk
Before building custom authentication flows, read the following sections to get a general understanding of how authentication flows work in Clerk.
Sign-up flow
The object is the pivotal concept in the sign-up process. It is used to gather the user's information, verify their email address or phone number, add OAuth accounts, and finally, convert them into a .
Every SignUp
must meet specific requirements before being converted into a User
. These requirements are defined by the instance settings you selected in the Clerk Dashboard. For example, on the User & authentication page, you can configure email and password, email links, or SMS OTP as authentication strategies.
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 progressive multi-step sign-up forms.
The following steps outline the sign-up process:
- Initiate the sign-up process by collecting the user's authentication information and passing the appropriate parameters to the method.
- Prepare the verification.
- Attempt to complete the verification.
- If the verification is successful, set the newly created session as the active session by passing the
SignIn.createdSessionId
to the method on theClerk
object. - Check for any pending tasks that need to be completed by accessing . Refer to session tasks
The state of a SignUp
The SignUp
object will show the state of the current sign-up in the status
property.
If you need further help on where things are and what you need to do next, you can also consult the required_fields
, optional_fields
, and missingFields
properties.
- Name
requiredFields
- Description
All fields that must be collected before the
SignUp
converts into aUser
.
- Name
optionalFields
- Description
All fields that can be collected, but are not necessary to convert the
SignUp
into aUser
.
- Name
missingFields
- Description
A subset of
requiredFields
. It contains all fields that still need to be collected before aSignUp
can be converted into aUser
. Note that this property will be updated dynamically. As you add more fields to theSignUp
, they will be removed. Once this property is empty, yourSignUp
will automatically convert into aUser
.
Verified fields
Some properties of the SignUp
, such as emailAddress
and phoneNumber
, must be verified before they are fully added to the SignUp
object.
The SignUp
object will show the state of verification in the following properties:
- Name
unverifiedFields
- Description
A list of all 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.
- Name
verifications
- Description
An object that describes the current state of verification for the . There are currently three different keys:
email_address
,phone_number
, andexternal_account
.
Sign-in flow
The object is the pivotal concept in the sign-in process.
Sign-ins are initiated by creating a SignIn
object on the current Client
. If the sign-in is successfully authenticated, it will transform into an active session for that on the current Client
.
The following steps outline the sign-in process:
- Initiate the sign-in process by collecting the user's authentication information and passing the appropriate parameters to the method.
- 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 address, or providing proof of their identity through an external social account (SSO/OAuth).
- Attempt to complete the first factor verification.
- 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.
- Attempt to complete the second factor verification.
- If verification is successful, set the newly created session as the active session by passing the
SignIn.createdSessionId
to the method on theClerk
object. - Check for any pending tasks that need to be completed by accessing . Refer to session tasks
Session tasks
Session tasks require users to complete specific actions after authentication, such as selecting an organization. These tasks ensure that users meet all requirements before gaining full access to your application.
For detailed information about configuring and implementing session tasks, see the session tasks overview.
Steps to handle session tasks
After completing the sign-up or sign-in process, you should check if the user has any pending tasks:
- Check for pending tasks: Use the
navigate
parameter in to accesssession.currentTask
and check for pending session tasks. - Handle the task: If a task exists, build UI to guide the user through completing the required action based on the task type. See the available task types to understand what actions may be required.
- Complete the flow: Once all required tasks are completed, the session becomes fully
active
and the user can access protected content.
You can build your own UI to handle specific task types. For example, if the task is choose-organization
, you can create a custom organization creation component to allow users to create or select an organization before proceeding.
Protect pages against pending task
When auth.protect()
detects a pending session, it redirects to /tasks
under the sign-in page. Create this page to handle the pending task and redirect the user appropriately.
'use client'
import { RedirectToTasks } from '@clerk/nextjs'
export default function Page() {
return <RedirectToTasks />
}
Next steps
Now that you have a general understanding of how authentication flows work in Clerk, you can start building your custom flows. To get started, choose the guide that best fits your needs from the navigation on the left.
Feedback
Last updated on