​
User metadata

​
Create user 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: 
curl --request POST \
  --url 'https://{yourDomain}/api/v2/users' \
  --header 'authorization: Bearer MGMT_API_ACCESS_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"email": "jane.doe@example.com", "user_metadata": {"hobby": "surfing"}, "app_metadata": {"plan": "full"}}'

​
Update user metadata

You can update a user’s metadata by making a PATCH call to the Management API /patch_users_by_id endpoint. 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: 
curl --request PATCH \
  --url 'https://{yourDomain}/api/v2/users/user_id' \
  --header 'authorization: Bearer MGMT_API_ACCESS_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"user_metadata": {"addresses": {"home": "123 Main Street, Anytown, ST 12345"}}}'
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 send a PATCH call in which you have set a property’s value to null (for example, {user_metadata: {color: null}}), Auth0 deletes the property/value from the database. Also, patching the metadata itself with an empty object removes the metadata completely.

​
Merge user metadata

Only properties at the root level are merged into the object. All lower-level properties will be replaced. 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: 
curl --request PATCH \
  --url 'https://{yourDomain}/api/v2/users/user_id' \
  --header 'authorization: Bearer MGMT_API_ACCESS_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"user_metadata": {"addresses": {"home": "123 Main Street, Anytown, ST 12345", "work": "100 Industrial Way, Anytown, ST 12345"}}}'

​
Delete user metadata

You can delete user_metadata: 
{
  "user_metadata": {}
}

​
App metadata

Patching the metadata with an empty object removes the metadata completely. For example, sending this body removes everything in app_metadata: 
{
  "app_metadata": {}
}

​
Client metadata

​
Create applications with client metadata

A clientMetadata object can be included when creating a new application via the POST /api/v2/ applications endpoint.

​
Read client metadata

Client metadata is included in the response to the GET /api/v2/clients and GET /api/v2/client/{id} endpoints.

​
Update client metadata

Client metadata can be updated using the PATCH /api/v2/clients/{id} endpoint, supplying an application object with the clientMetadata property, which has a value that consists of an object containing the metadata you’d like to change. Application before: 
{
  ...
  "name": "myclient",
  "client_metadata": {
    "mycolor": "red",
    "myflavor": "grape"
  }
  ...
}
Request: PATCH /api/v2/client/myclientid123 with body: 
{ "client_metadata": { "mycolor": "blue" } }
Application after: 
{
  "name": "myclient",
  "client_metadata": {
    "mycolor": "blue",
    "myflavor": "grape"
  }
  ...
}

​
Delete client metadata properties and values

Client metadata keys can be removed by issuing a PATCH, as described in “Update app_metadata” above, but supplying null for the key value. This behavior matches that of the user_metadata and app_metadata properties in the PATCH /api/v2/users/ endpoint.

​
Learn more