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.