Manage Metadata Using the Management API

Learn how to create, update, merge, and delete metadata with the Management API.

User metadata

Create user metadata

To create a user with the following profile details:

{
    "email": "[e-mail]",
    "user_metadata": {
        "hobby": "surfing"
    },
    "app_metadata": {
        "plan": "full"
    }
}

Make the following POST call to the Management API /post_users endpoint to create the user and set the property values:

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": "[e-mail]",
    "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:

The user’s profile will now appear as follows:

{
    "email": "[e-mail]",
    "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:

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

• Management API Access Tokens
• Configure Application Metadata