Understand How Metadata Works in User Profiles
Auth0 provides a comprehensive system for storing metadata in the Auth0 user profile. You can use metadata to do the following activities:
Store application-specific data in the user profile.
Record whether or not specific operations have occurred for a user.
Cache the results of expensive operations on the user profile so they can be re-used in future logins.
Store information that does not originate from an identity provider or that overrides what an identity provider supplies.
The metadata can be modified as part of a user’s login flow.
You can configure connection sync so that user root attributes are updated by the identity provider only on user profile creation. You can then edit root attributes individually or by bulk import. To learn more, read Configure Identify Provider Connection for User Profiles Updates.
Metadata types
Auth0 uses three types of metadata to store specific kinds of information.
| Metadata Type | Field Name | Description |
|---|---|---|
| User Information | user_metadata |
Stores user attributes such as preferences that do not impact a user's core functionality. This data can be edited by logged in users if you build a form using the Management API and should not be used as a secure data store. |
| Access Information | app_metadata |
Stores information such as permissions, Auth0 plan, and external IDs that can impact user access to features. This data cannot be edited by users and there are restrictions for what can be stored in this field. |
| Application Information | client_metadata in the Client object, context.clientMetadata in Rules, and event.client.metadata in post-login Actions. |
Stores information about an application (or client in OIDC OAuth2 terminology). For example, the URL for the application home page (any value that Auth0 doesn’t set in the application settings). |
Manage metadata
You can create and update metadata using Rules, the Authentication API, the Management API, the Auth0 Dashboard, and the Lock library.
It is not recommended that app_metadata or user_metadata be returned by
custom DB scripts
the
fetchUserProfilescript of custom social connections
Use Rules
Rules are JavaScript functions executed as part of the Auth0 authentication process (prior to authorization). Using rules, you can read, create, or update user metadata and have such changes affect the results of the authorization process.
To learn more, read Manage Metadata with Rules.
You can also use the GET /userinfo endpoint to get a user's user_metadata, however, you must first write a Rule to copy user_metadata properties to the ID token.
Use the Management API
A user can request an access token with the appropriate scopes and use the following Management API endpoints to view, create, update, and delete user_metadata.
| Task | Endpoint | Scope |
|---|---|---|
| View | GET /api/v2/users/{id} |
read:current_user |
| Create | PATCH /api/v2/users/{id} |
create:current_user_metadata |
| Update | PATCH /api/v2/users/{id} |
update:current_user_metadata |
| Delete | DELETE /api/v2/users/{id}/multifactor/{provider} |
delete:current_user_metadata |
An access token is required to call the Auth0 Management API. To learn more, read Access Tokens for the Management API and Get Management API Tokens for SPAs.
Use the Dashboard
Use the Auth0 Dashboard to configure application metadata which contains key/value pairs. To learn more, read Configure Application Metadata.
Use the Lock library
Use the Lock library to define, add, read, and update user_metadata. Read user_metadata properties the same way you would read any other user profile property. For example, the following code snippet retrieves the value associated with user_metadata.hobby and assigns it to an element on the page:
// Use the accessToken acquired upon authentication to call getUserInfo
lock.getUserInfo(accessToken, function(error, profile) {
if (!error) {
document.getElementById('hobby').textContent = profile.user_metadata.hobby;
}
});Was this helpful?
You can use additionalSignUpFields to add custom fields to user sign-up forms. When a user adds data in a custom field, Auth0 stores entered values in that user's user_metadata. To learn more about adding user_metadata on signup, read Additional Signup Fields.
Custom database connections and metadata
If you have a custom database connection, you can use the Authentication API /dbconnections/signup endpoint to set the user_metadata for a user. To learn more about working with metadata during a custom signup process, read Custom Signup.
When you set the user_metadata field using the Authentication API /dbconnections/signup endpoint, you are limited to a maximum of 10 string fields and 500 characters.
Custom emails and metadata
Use metadata to store information that you want to use to customize Auth0 emails. For example, use user_metadata.lang if you want the user to be able to change the field's value, then use the information to customize the language for an email. To learn more, read Customize Email Templates.
If you are having issues with Lock, review Deprecation Errors. If you are having issues with the Management API, review Check API Calls