User Metadata

Auth0 provides you with metadata fields to store individual user information that did not originate with an identity provider. Auth0 distinguishes between two types of metadata:

  • User metadata: used to store user attributes (e.g., user preferences) that do not impact a user's core functionality;
  • App metadata: used to store information (e.g., 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.

You can read, create, and edit user metadata using Rules, Auth0 APIs, and Lock.

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.

For more information and examples refer to User Metadata in Rules.

Auth0 APIs

When you use the Authentication API, you can use the Signup endpoint to set the user_metadata for a user. This endpoint only works for database connections.

For an example of working with metadata during a custom signup process, see Custom Signup > Using the API.

You can also use the GET /userinfo endpoint in order to get a user's user_metadata. To do so, you first have to write a Rule to copy user_metadata properties to the ID Token.

You can use the Management API in order to retrieve, create, or update both the user_metadata and app_metadata fields at any point.

Endpoint Description
Search user by id Use this if you want to search for a user based on Id. For an example request see User Search.
Search user by email Use this if you want to search for a user based on email. For an example request see User Search.
Get a list of users Use this if you want to search for a list if users with other search criteria. For an example request see User Search. See also Export Metadata for limitations.
Create User Create a new user and (optionally) set metadata. For a body sample see POST /api/v2/users.
Update User Update a user using a JSON object. For example requests see PATCH /api/v2/users/{id}.

For examples and more information, see Manage User Metadata.

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.

Metadata and custom databases

If you are using a custom database, the app_metadata field should be referred to as metadata in the scripts you run to manage your metadata.

For example, you would not use this:

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

Instead, you would use this:

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

Keep reading