Metadata

Auth0 allows you to store metadata, or data related to each user that has not come from the identity provider. There are two kinds of metadata:

  • user_metadata: stores user attributes (such as user preferences) that do not impact a user's core functionality;
  • app_metadata: stores information (such as a user's support plan, security roles, or access control groups) that can impact a user's core functionality, such as how an application functions or what the user can access.

An authenticated user can modify data in their profile's user_metadata, but not in their app_metadata.

How to Read, Create, or Edit Metadata

There are two ways by which you can manage your user metadata:

  1. Rules
  2. Auth0 APIs

Rules

Rules are JavaScript functions executed as part of the Auth0 authentication process (prior to authorization). You can therefore read, create, or update user metadata and have such changes affect the results of the authorization process.

Auth0 APIs

When using the Authentication API, you can set the user_metadata field of a newly-created user for a Database Connection with the Signup endpoint.

The Management API, can be used to create and update both the user_metadata and app_metadata fields at any point during the authentication/authorization processes.

Metadata Usage

Suppose the following metadata is stored for a user with the email address jane.doe@example.com:

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

Any valid JSON snippet can be used as metadata.

To read metadata, simply access the correct property as you would from any JSON object. For example, if you were working with the above example metadata within a Rule or via a call to the Management API, you could reference specific items from the data set as follows:

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

With Management APIv1, all metadata was stored in the metadata field. Data stored in this field is now available under app_metadata.

Rules on Naming Metadata Fields

The following sections cover best practices when setting the names of your metadata fields.

Avoid Periods and Ellipses

Metadata field names must not contain a dot. For example, use of the following field name would return a Bad Request (400) error:

{
    "preference.color": "pink"
}

One way of handling this limitation is to nest attributes:

{
    "preference": {
        "color": "pink"
    }
}

Alternately, you can use any delimiter that is not . or $.

However, the usage of the . delimiter is acceptable in the data values such as in the below example:

{
    "preference": "light.blue"
}

Avoid Dynamic Field Names

Do not use dynamic field names. For example, instead of using the following structure:

"participants": {
    "Alice" : {
        "role": "sender"
    },
    "Bob" : {
        "role": "receiver"
    }
}

Use this:

"participants": [
    {
        "name": "Alice",
        "role": "sender"
    },
    {
        "name" : "Bob",
        "role": "receiver"
    }
]

Searching Metadata

Beginning 1 September 2017, new tenants cannot search any of the app_metadata fields. Tenants associated with paid subscriptions that were created on/before 31 August 2017 can search the app_metadata fields.

When searching user_metadata, you can only search for profile-related information, such as name, nickname, given_name, or family_name.

Metadata Restrictions

There are some restrictions when using metadata of which you should be aware:

Field Restrictions

The following fields may not be stored in the app_metadata field:

  • blocked
  • clientID
  • created_at
  • email
  • email_verified
  • global_client_id
  • globalClientID
  • identities
  • lastIP
  • lastLogin
  • metadata
  • user_id
  • loginsCount

Metadata Size Limits

Currently, Auth0 limits the total size of your user metadata to 16 MB. However, when using Rules and/or the Management Dashboard, your metadata limits may be lower.

When setting the user_metadata field with the Authentication API Signup endpoint, your metadata is limited to a maximum of 10 fields and 500 characters.

Using Lock to Manage Metadata

Users of the Lock widget are able to add new items to user_metadata, as well as read user_metadata after authentication.

  • For information on adding user_metadata on signup, please see Additional Signup Fields
  • When using Lock, you can read the user's user_metadata properties the same way you would for 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;
  }
});

For details on how to use Lock to authenticate users and access their profile information, check out the Lock documentation.

Keep Reading