How to Manage User Profile Metadata

You can access and set user_metadata and app_metadata in user profiles using a variety of methods depending on your use case.

Management API
post-login Action
Lock
Rules

When you create a new user with the Management API’s Create a User endpoint (POST /users), you can set the new user’s metadata by specifying the body parameters for user_metadata and app_metadata.

Example: create new user with metadata

To create a user with the following profile details:

{
    "email": "jane.doe@example.com",
    "user_metadata": {
        "hobby": "surfing"
    },
    "app_metadata": {
        "plan": "full"
    }
}

Make the following POST call to the /post_users endpoint to create the user and set the property values:

Using the Auth0 CLI? If you haven’t already, set up and authenticate your CLI session before running this command.

You can set or update an existing user’s metadata with the Update a User endpoint (PATCH /users/{id}) by similarly specifying the body parameters for user_metadata and app_metadta.

Example: update an existing user's metadata

Assuming you created a user with the following metadata values:

{
    "email": "jane.doe@example.com",
    "user_metadata": {
        "hobby": "surfing"
    },
    "app_metadata": {
        "plan": "full"
    }
}

To update user_metadata and add the user’s home address as a second-level property:

{
    "addresses": {
        "home": "123 Main Street, Anytown, ST 12345"
    }
}

You would make the following PATCH call:The user’s profile will now appear as follows:

{
    "email": "jane.doe@example.com",
    "user_metadata": {
        "hobby": "surfing",
        "addresses": {
            "home": "123 Main Street, Anytown, ST 12345"
        }
    },
    "app_metadata": {
        "plan": "full"
    }
}

When you update an existing user’s metadata, only properties at the root level are merged into the object. All lower-level properties will be replaced.

Example: update metadata sub-properties

For example, to add a user’s work address as an additional inner property, you would have to include the complete contents of the addresses property. Since the addresses object is a root-level property, it will be merged into the final JSON object representing the user, but its sub-properties will not.

{
  "user_metadata": {
    "addresses": {
      "home": "123 Main Street, Anytown, ST 12345",
      "work": "100 Industrial Way, Anytown, ST 12345"
    }
  }
}

Therefore, the corresponding PATCH call to the API would be:

To delete a metadata key, make a PATCH call and set the metadata key’s value to null (for example, { "user_metadata": {"color": null}}).To delete user or app metadata entirely, make a PATCH call and set the metadata itself to an empty object (for example, { "user_metadata": {} }).

You can configure a post-login trigger to modify user_metadata and app_metadata as part of a user’s login flow.Post-login triggers are useful for tasks such as storing application-specific data on the user profile, capturing user operation logs, mapping attributes to the metadata field, or caching expensive operation values on the User profile for re-used in future logins.The post-login api object provides common operations that can be performed in this trigger. To manage user metadata, we want to use the api.user.setAppMetadata and api.user.setUserMetadata methods. For example, to guard against some behavior running more than once for a specific user, consider an Action that looks like this:

exports.onExecutePostLogin = async (event, api) => {
  if (event.user.app_metadata.didAnExpensiveTask) {
    console.log(`Skipping the expensive task because it already occurred for ${event.user.email}.`);

    return;
  }
  // do and expensive task
  api.user.setAppMetadata("didAnExpensiveTask", true);
};

Here, we added a check at the start of the Action to see if we have already performed the expensive task for this user. If the metadata field exists, then we return from the function.At the end of the Action, we call api.user.setAppMetadata to signal that we would like to store some metadata on the user object. At the end of each trigger’s execution, Actions will update the user profile as a single operation. If several calls are made to setUserMetadata actions, even if they are made in different actions as part of the same flow, Actions will only update the user profile a single time—at the end of the trigger’s execution.

Multiple setUserMetadata or setAppMetadata calls will be batched together into a single user profile update at the end of the trigger’s execution, even if they are made by different Actions.

In the event of a Redirect invoked with api.redirect.sendUserTo(), any pending user or app metadata updates will be applied to the user profile before the user is redirected to the external site.

You can use the Lock library to define, add, read, and update the user_metadata. You can read the user’s 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;
  }
});

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.

Rules will reach end of life (EOL) on January 31, 2028.

As of October 16, 2023, Rules are no longer available in newly created tenants.
As of November 18, 2024, Rules are read-only. Active Rules still run, and you can enable or disable them and change their configuration values and secrets. You can’t edit their code in the Dashboard, the Management API, or tools that use it, such as the Auth0 CLI, Deploy CLI, Terraform, and Agent Skills.
After January 31, 2028, Rules stop running and are removed.

Use Actions to extend Auth0:

To learn more about Actions, read Understand How Auth0 Actions Work.
To migrate, read Migrate from Rules to Actions.

You can read, update, and delete metadata using Auth0 Rules. The following sections refer to this example where the user and their information is represented by the following JSON snippet:

{
  "user_id": "jdoe",
  "email": "john.doe@example.com",
  "app_metadata": {
    "roles": [ "writer" ]
  },
  "user_metadata": {
    "preferences": {
      "color": "blue"
    }
  }
}

Read metadata

You can read metadata using rules with the . You can also search for profile-related information in user_metadata, such as:

name
nickname
given_name
family_name

As an example, assume the following metadata is stored for a user with the email address jane.doe@example.com:

{
    "email": "jane.doe@example.com",
    "user_metadata": {
        "hobby": "surfing"
    },
    "app_metadata": {
        "plan": "full"
    }
}

Using the example metadata above, you can refer to specific items from the dataset in Auth0 Rules or via a call to the Management API as follows:

console.log(user.email); // "jane.doe@example.com"
console.log(user.user_metadata.hobby); // "surfing"
console.log(user.app_metadata.plan); // "full"

Any valid JSON snippet can be used as metadata. user.app_metadata is Undefined by default.

Example: conditional on metadata

You can make a decision based on the user’s roles:

function(user, context, callback){
  user.app_metadata = user.app_metadata || {};
  if (user.app_metadata.roles.indexOf('writer')){
    // code to be executed
  }
}

You can base decisions on specific preferences, such as a color preference:

function(user, context, callback){
  user.user_metadata = user.user_metadata || {};
  if (user.user_metadata.preferences.color === 'black'){
    // code to be executed
  }
  ...
}

Read application metadata (clientMetadata)

Application metadata (clientMetadata) is an optional, top-level property of the context object. Existing applications will have no value for this property.

function(user, context, callback){
  context.clientMetadata = context.clientMetadata || {};
  if (context.clientMetadata.usersuppliedkey1 === 'black'){
    // this code would not be executed for the user
  }
  ...
}

Update metadata

You can use Rules to map SAML attributes that Auth0 receives from the IdP into user_metadata or app_metadata.

Update app metadata

To add an administrative role to the user:

function(user, context, callback){
  user.app_metadata = user.app_metadata || {};
  // update the app_metadata that will be part of the response
  user.app_metadata.roles = user.app_metadata.roles || [];
  user.app_metadata.roles.push('administrator');

  // persist the app_metadata update
  auth0.users.updateAppMetadata(user.user_id, user.app_metadata)
    .then(function(){
      callback(null, user, context);
    })
    .catch(function(err){
      callback(err);
    });
}

This results in the following JSON representation of the user profile details:

{
  "user_id": "jdoe",
  "email": "john.doe@example.com",
  "app_metadata": {
    "roles": [ "writer", "administrator" ]
  },
  "user_metadata": {
    "preferences": {
      "color": "blue"
    }
  }
}

Update user metadata

To add the user’s fontSize preference to the user profile:

function(user, context, callback){
  user.user_metadata = user.user_metadata || {};
  // update the user_metadata that will be part of the response
  user.user_metadata.preferences = user.user_metadata.preferences || {};
  user.user_metadata.preferences.fontSize = 12;

  // persist the user_metadata update
  auth0.users.updateUserMetadata(user.user_id, user.user_metadata)
    .then(function(){
      callback(null, user, context);
    })
    .catch(function(err){
      callback(err);
    });
}

This results in the following JSON representation of the user profile details:

{
  "user_id": "jdoe",
  "email": "john.doe@example.com",
  "app_metadata": {
    "roles": [ "writer" ]
  },
  "user_metadata": {
    "preferences": {
      "color": "blue",
      "fontSize": 12
    }
  }
}

Update app and user metadata simultaneously

To reduce the rule’s processing time, you may update both the app_metadata and user_metadata in the same rule:

function(user, context, callback){

  var q = require('q');

  user.app_metadata = user.app_metadata || {};
  user.user_metadata = user.user_metadata || {};
  // update the user_metadata that will be part of the response
  user.user_metadata.preferences = user.user_metadata.preferences || {};
  user.user_metadata.preferences.fontSize = 12;

  // update the app_metadata that will be part of the response
  user.app_metadata.roles = user.app_metadata.roles || [];
  user.app_metadata.roles.push('admin');

  // persist the app_metadata update
  var appMetadataPromise  = auth0.users.updateAppMetadata(user.user_id, user.app_metadata);

  // persist the user_metadata update
  var userMetadataPromise = auth0.users.updateUserMetadata(user.user_id, user.user_metadata);

  // using q library to wait for all promises to complete
  q.all([userMetadataPromise, appMetadataPromise])
    .then(function(){
      callback(null, user, context);
    })
    .catch(function(err){
      callback(err);
    });
}

This results in the following JSON representation of the user profile details:

{
  "user_id": "jdoe",
  "email": "john.doe@example.com",
  "app_metadata": {
    "roles": [ "writer", "admin" ]
  },
  "user_metadata": {
    "preferences": {
      "color": "blue",
      "fontSize": 12
    }
  }
}

Delete metadata

Delete app metadata properties and values

To delete a property, set the property’s value to null.

Delete user’s roles example

To delete the user’s roles, use the following sample rule:

function(user, context, callback){
  user.app_metadata = user.app_metadata || {};
  // update the app_metadata that will be part of the response
  user.app_metadata.roles = null;

  // persist the app_metadata update
  auth0.users.updateAppMetadata(user.user_id, user.app_metadata)
    .then(function(){
      callback(null, user, context);
    })
    .catch(function(err){
      callback(err);
    });
}

This results in the following JSON representation of the user profile:

{
  "user_id": "jdoe",
  "email": "john.doe@example.com",
  "app_metadata": { },
  "user_metadata": {
    "preferences": {
      "color": "blue"
    }
  }
}

Delete single property value example

To delete a single value of a property, remove that specific value. For example, to remove the writer role from the user profile:

function(user, context, callback){
  user.app_metadata = user.app_metadata || {};
  user.app_metadata.roles = user.app_metadata.roles || [];

  var index = user.app_metadata.roles.indexOf('writer');

  if (index !== -1){
    // update the app_metadata that will be part of the response
    user.app_metadata.roles.splice(index, 1);
  }

  // persist the app_metadata update
  auth0.users.updateAppMetadata(user.user_id, user.app_metadata)
    .then(function(){
      callback(null, user, context);
    })
    .catch(function(err){
      callback(err);
    });
}

This results in the following JSON representation of the user profile:

{
  "user_id": "google-oauth2|1234",
  "email": "john.doe@gmail.com",
  "app_metadata": {
    "roles": [ ]
  },
  "user_metadata": {
    "preferences": {
      "color": "blue"
    }
  }
}

The roles property still exists but does not contain any value.

Delete user metadata properties and values

To delete the user’s color preference:

function(user, context, callback){
  user.user_metadata = user.user_metadata || {};
  // update the user_metadata that will be part of the response
  user.user_metadata.preferences = user.user_metadata.preferences || {};
  delete user.user_metadata.preferences.color;

  // persist the user_metadata update
  auth0.users.updateUserMetadata(user.user_id, user.user_metadata)
    .then(function(){
      callback(null, user, context);
    })
    .catch(function(err){
      callback(err);
  });
}

This results in the following JSON representation of the user profile details:

{
  "user_id": "jdoe",
  "email": "john.doe@example.com",
  "app_metadata": {
    "roles": [ "writer" ]
  },
  "user_metadata": {
    "preferences": { }
  }
}

Concepts

How To

Reference

Use Cases

How to Manage User Profile Metadata

Read metadata

Read application metadata (clientMetadata)

Update metadata

Update app metadata

Update user metadata

Update app and user metadata simultaneously

Delete metadata

Delete app metadata properties and values

Delete user’s roles example

Delete single property value example

Delete user metadata properties and values

​Read metadata

​Read application metadata (clientMetadata)

​Update metadata

​Update app metadata

​Update user metadata

​Update app and user metadata simultaneously

​Delete metadata

​Delete app metadata properties and values

​Delete user’s roles example

​Delete single property value example

​Delete user metadata properties and values

Read metadata

Read application metadata (clientMetadata)

Update metadata

Update app metadata

Update user metadata

Update app and user metadata simultaneously

Delete metadata

Delete app metadata properties and values

Delete user’s roles example

Delete single property value example

Delete user metadata properties and values