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.

For custom DB scripts and the fetchUserProfile script of custom social connections, you can create and update metadata using the metadata object.

Use Actions

Actions are secure, tenant-specific, versioned functions written in Node.js that execute at certain points within the Auth0 platform. Actions are used to customize and extend Auth0's capabilities with custom logic. They can also be used to enrich the user profile.

For example, you can create a post-login Action that uses custom claims to copy user_metadata properties to ID tokens. You can then retrieve users' user_metadata through the Get User Info endpoint of the Authentication API.

To learn more, read Manage User Metadata with the post-login Action Trigger.

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, or update user_metadata, or remove an MFA configuration.

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} update:users

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

Learn more