Manage Metadata with Rules
You can read, update, and delete metadata using Auth0 Rules. In the following sections, we will 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"
}
}
}
Was this helpful?
Read metadata
You can read metadata using rules with the Management API. You can also search for profile-related information in user_metadata
, such as:
name
nickname
given_name
family_name
By default, user profile attributes provided by identity providers other than Auth0 (such as Google, Facebook, or X) are not directly editable because they are updated from the identity provider each time the user logs in.
To be able to edit the name
, nickname
, given_name
, family_name
, or picture
root attributes on the normalized user profile, you must configure your connection sync with Auth0 so that user attributes will be updated from the identity provider only on user profile creation. These root attributes will then be available to be edited individually or by bulk imports
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"
}
}
Was this helpful?
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"
Was this helpful?
Any valid JSON snippet can be used as metadata, but note that user.app_metadata
is Undefined
by default.
To read the available metadata, you will need to access the correct user property.
Read app 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
}
...
}
Was this helpful?
Read user metadata
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
}
...
}
Was this helpful?
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
}
...
}
Was this helpful?
Update 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);
});
}
Was this helpful?
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"
}
}
}
Was this helpful?
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);
});
}
Was this helpful?
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
}
}
}
Was this helpful?
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);
});
}
Was this helpful?
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
}
}
}
Was this helpful?
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);
});
}
Was this helpful?
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"
}
}
}
Was this helpful?
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);
});
}
Was this helpful?
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"
}
}
}
Was this helpful?
Note that 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);
});
}
Was this helpful?
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": { }
}
}
Was this helpful?