Remove the Gravatar Image for a Specific User

Problem statement

It may be desirable in some circumstances to remove the gravatar image for a specific user.

Setting “gravatar_disabled”: true in user_metadata did not have the desired outcome. So how can this image be changed or removed?


Gravatar is a cloud-based service, which hosts a custom picture of an individual user. Two points to note about how this service relates to Auth0:

  • Auth0 passively points to the location where the picture is stored, which minimizes the amount of data storage space that is required. For this reason, it is not possible to directly edit or remove the original source image within a user’s profile.
  • Not everyone uses the Gravatar service, which means that not all users will have a ‘gravatar’ image.

The Auth0 documentation contains multiple references to the use of ‘gravatars’. For example, in the context of usage with Lock and Wordpress.

More generally, in the context of this specific question, the requirement is to change the user picture , as defined by the 'user.picture ’ attribute. This is explained in the Change User’s Pictures documentation:

Auth0 normalizes common profile properties in the User Profile, this includes the name, picture field and more. The picture field is populated by either the social provider profile picture or the Gravatar image associated with the user’s email address.

By default, all database users will have a placeholder image with their initials. When you authenticate the user, this picture field is referred to as user.picture.

In general terms, picture is a root attribute that exists within a user profile.

Note that this user.picture attribute can only be directly edited if the user account is associated with an Auth0 database connection.


As described in the the Change User’s Pictures documentation, there are two cases to consider:

a) if the Identity Provider is a social connection such as X (formerly Twitter), Facebook, LinkedIn, a number of Sample User Profiles are available that illustrate how the user picture is stored within these types of social providers. In order to edit this picture attribute, it is necessary to configure connection sync with Auth0 so that user attributes will be updated from the identity provider only on user profile creation. To learn more, read Configure Identity Provider Connection for User Profile Updates.

b) if the Identity Provider is an Auth0 database connection, then metadata can be used to store the picture. This can be managed using the Management API to store a picture URL in the attribute user.user_metadata.picture

Note that this URL could point to a ‘gravatar’ image, as in this example. The general form of this call is shown in the following below:

curl --request PATCH \
  --url 'https://{yourDomain}/api/v2/users/USER_ID' \
  --header 'authorization: Bearer ABCD' \
  --header 'content-type: application/json' \
  --data '{"user_metadata": {"picture": ""}}'

In order to be useful to applications, the picture URL in the user_metadata must be present in the ID Token. In order to check whether the event.user.user_metadata.picture attribute is present. This can be performed through use of an Action, the general form of which can be seen in this example:

exports.onExecutePostLogin = async (event, api) => {
  const { picture } = event.user.user_metadata;
  if (picture) {
    // Return the persisted user_metadata.picture in the ID token
    api.idToken.setCustomClaim("picture", picture)

The details of this approach are described more fully in the Use Actions section of the documentation.

Regarding the initial observation: “Setting “gravatar_disabled”: true in user_metadata did not have the desired outcome.” It is possible that specific ‘gravatar’ control options may appear within the context of individual product features such as the Lock configuration. However, for all other purposes, the general approach described in this document should be followed. To remove a user picture, make a Management API call to update the user and then assign an empty string to the picture attribute.