Core concepts

Before building your application, it's important to understand the core concepts and objects that drive Clerk's powerful authentication and user management system. This page walks through integration options, prebuilt components, configuration steps, and the key objects you'll use as you build your application.

Ways to implement Clerk

Clerk provides three ways to integrate authentication into your application, depending on the level of control and customization you need:

1. Account Portal (default): Uses Clerk's prebuilt components on dedicated pages that are hosted on Clerk servers. Every Clerk application has this enabled by default, providing a complete user management interface out of the box.
2. Prebuilt components: All-in-one UI components that can be integrated into your application. They are fully customizable to match your application's branding and design. This is the recommended approach for most use cases.
3. Custom flows using the Clerk API: Build your own UI using the Clerk API. This option provides maximum flexibility and control over the user experience but requires more development effort.

Clerk offers a comprehensive suite of prebuilt components designed to seamlessly integrate authentication and multi-tenancy into your application. Components, like <SignIn />, <UserButton />, and <OrganizationSwitcher />, are all-in-one solutions that handle the full lifecycle of the user experience, from sign-up/sign-in to user profile and organization management.

The Account Portal uses these components on dedicated pages that are hosted on Clerk servers. These pages cannot be customized beyond the options provided in the Clerk Dashboard⁠.

For more control and customization, you can migrate away from the Account Portal and embed the prebuilt components directly into your own application pages. While they are fully customizable to match your application's branding and design using CSS or special props, the HTML structure and the logic/ordering of the authentication flow remain fixed.

If the prebuilt components don't meet your specific needs or if you need complete control over the logic, you can rebuild the existing Clerk flows using the Clerk API. However, this is more advanced and it's recommended to use the prebuilt components whenever possible.

Configuring your application

Configuring your application is done through the Clerk Dashboard⁠. The Clerk Dashboard is where you, as the application owner, can manage your application's settings, users, and organizations.

For example, you can:

• Enable phone number authentication or multi-factor authentication.
• Add social providers like Google.
• Delete users or create organizations.
• Invite other users to your workspace to help configure and manage your application.

To get started, see the configuration docs, which include dedicated guides for specific configuration options.

Building your application

The Clerk JavaScript SDK, or ClerkJS, is where Clerk all started. It is the core SDK that powers all other JavaScript SDKs, including React and Next.js. The following sections will introduce you to the main objects that make up ClerkJS.

Clerk

The Clerk class is the main entry point for the Clerk JavaScript SDK. All other objects are accessible from the Clerk object. As you're building your application, you'll likely interact with these objects, either directly or through helpers provided by the other SDKs, like React hooks or Vue composables.

Client

A client represents the current device or software accessing an application such as your web browser, native application, or Chrome Extension. It is represented by the Client object.

Session

A session is a secure representation of the authentication state of the current user. Each client can hold multiple sessions on the same device. It is represented by the Session object.

User

The User object represents the current user of the session. It holds all the basic user information such as the user's name, email addresses, and phone numbers, and including their public, private, and unsafe metadata.

Organization

Organizations are a flexible and scalable way to manage users and their access to resources within your Clerk application. With organizations, you can assign specific roles and permissions to users, making them useful for managing projects, coordinating teams, or facilitating partnerships.

Users can belong to many organizations. One of them will be the "active organization" of the session. It is represented by the Organization object. To learn about organizations, see the dedicated guide.

Sign in

The SignIn object holds the state of the current sign-in and provides helper methods to navigate and complete the sign-in process. It is used to manage the sign-in lifecycle, including the first and second factor verification, and the creation of a new session.

Sign up

The SignUp object holds the state of the current sign-up and provides helper methods to navigate and complete the sign-up process. Once a sign-up is complete, a new user is created.