The User object
The User object models a user's account information.
User object contains all account information that describes a user of your app in Clerk. Users can authenticate and manage their accounts, update their personal and contact info, or set up security features for their accounts.
For more information on users, see the User object reference.
Users can be created through the Sign up flow. They have to provide a unique authentication identifier which can be an email address, phone number, or username.
If the sign up attempt succeeds, a new session and user are created for your application instance.
Whenever you have an active session, that means you can access the currently signed in
User object, through the
You can uniquely identify your users in two ways; either through their Clerk unique identifier (their
id), or their unique authentication identification, as described above.
It is strongly recommended that you verify your user's identification (email address, phone number) upon sign up. Clerk currently asks for verification by default.
There are currently many different ways to verify your user's unique authentication identifier and they vary depending on what that identifier is.
- Email addresses can be verified via magic links, one-time codes or through a trusted social (OAuth) provider.
- Phone numbers can be verified via one-time codes that are sent with SMS.
- Usernames must be guaranteed to be unique and can be verified only through a trusted social (OAuth) provider.
Users can be contacted at their primary email address or primary phone number.
They can have more than one registered email addresses, but only one of them will be their primary email address. Same thing with phone numbers; they can have more than one, but only one will be their primary.
Clerk takes care of automatically assigning a verified email address or phone number as the user's primary contact method, but users are allowed to pick one through their account settings as well.
Custom user metadata
User objects hold a set of metadata that can be used internally to store arbitrary information.
The metadata are split into public and private. Both types are set from the Backend API, but public metadata can be accessed from the Frontend API and Backend API. These types of metadata can be used to access non-sensitive information about a user, such as their profile picture or their name. They can be used to build UIs where a user might not be signed in, but you still want to show some of their profile info.
There's also a third kind of metadata which are called "unsafe", since they can be set and accessed by both the Frontend API and the Backend API. They provide a quick method to add custom attributes to a user. These attributes will be stored on the
User object and will be available for access at all times.
The "unsafe" custom attributes can be set upon sign up, when creating or updating a
SignUp object. After a successful sign up, these attributes will be copied to the
User object. From that point on they can be accessed as a direct attribute of the
Here's a comparison of the different metadata attributes on the User object and how each can be used.
|Metadata||Frontend API||Backend API|
Choosing which metadata field you should use for setting custom attributes on your users becomes a matter of access and visibility.
Do you need to set the custom attributes from the front-end (using our ClerkJS library or the Frontend API)? You should choose the unsafeMetadata property.
Will the custom attributes contain sensitive information that should not be displayed on the front-end? Use the privateMetadata property.
Do you need to set some metadata from your back-end and have them displayed as read-only on the front-end? Use the publicMetadata property.
Looking for inspiration on how to set custom user attributes? Our Clerk Widget starter repo demonstrates storing additional user info like their company, country, and whether they accept the terms and conditions.
Update user profiles
User objects hold profile data like their name, a profile photo, email addresses, phone numbers, connected OAuth accounts and a set of metadata that can be used internally to store arbitrary information.
Clerk provides ready-made components and hosted pages that enable updating a user's profile out of the box.
User account security
Regarding account security, Clerk provides features that strengthen a user's account with little effort.
Users can enable multi-factor authentication for their accounts. In this case, every time they successfully authenticate, they must complete an additional challenge to verify their identity. Currently, only SMS based multi-factor authentication is supported, and it can be enabled by creating a phone number for the
User object and then configuring it for multi-factor authentication.
Users can also change their password. Frequently updating a password leads to safer authentication. Even if a password is compromised, the new one can still be used to sign in. You can change a user's password by simply updating the
Finally, users can get a list of their active sessions and information about the device they signed in from.
Clerk allows user accounts to be deleted. Currently, this can be done only through the Backend API.