IMPORTANT: No additional bug fixes or documentation updates will be released for this version. For the latest information, see the current release documentation.

« Suggest user profile API Snapshot and restore APIs »

› › ›

Update user profile data API

edit

Update user profile data API

edit

This feature is in development and not yet available for use. This documentation is provided for informational purposes only.

Updates specific data for the user profile that’s associated with the specified unique ID.

Request

edit

POST /_security/profile/<uid>/_data

Prerequisites

edit

To use this API, you must have one of the following privileges:

The manage_user_profile cluster privilege.
The update_profile_data global privilege for the namespaces that are referenced in the request.

Description

edit

The update user profile API updates the labels and data fields of an existing user profile document with JSON objects. New keys and their values are added to the profile document, and conflicting keys are replaced by data that’s included in the request.

For both labels and data, content is namespaced by the top-level fields. The update_profile_data global privilege grants privileges for updating only the allowed namespaces.

Path parameters

edit

uid: (Required, string) A unique identifier for the user profile.

Query parameters

edit

if_seq_no: (Optional, integer) Only perform the operation if the document has this sequence number. See Optimistic concurrency control.
if_primary_term: (Optional, integer) Only perform the operation if the document has this primary term. See Optimistic concurrency control.
refresh: (Optional, enum) If true, Elasticsearch refreshes the affected shards to make this operation visible to search, if wait_for then wait for a refresh to make this operation visible to search, if false do nothing with refreshes. Valid values: true, false, wait_for. Default: false.
uid: (Required, string) A unique identifier for the user profile.

Request body

edit

labels: (Required*, object) Searchable data that you want to associate with the user profile. This field supports a nested data structure. Within the labels object, top-level keys cannot begin with an underscore (_) or contain a period (.).
data: (Required*, object) Non-searchable data that you want to associate with the user profile. This field supports a nested data structure. Within the data object, top-level keys cannot begin with an underscore (_) or contain a period (.) The data object is not searchable, but can be retrieved with the Get user profile API.

*Indicates that the setting is required in some, but not all situations.

Response body

edit

A successful update user profile data API call returns a JSON structure indicating that the request is acknowledged:

{
  "acknowledged": true
}

Examples

edit

The following request updates a profile document for a uid matching u_kd2JMqwUQwSCCOxMv7M1vw:

POST /_security/profile/u_kd2JMqwUQwSCCOxMv7M1vw/_data
{
  "labels": {
    "app1": {
      "tag": "prod"
    }
  },
  "data": {
    "app1": {
      "theme": "default"
    }
  }
}

You can update the profile data to replace some keys and add new keys:

POST /_security/profile/u_kd2JMqwUQwSCCOxMv7M1vw/_data
{
  "labels": {
    "app1": {
      "tag": "dev"
    }
  },
  "data": {
    "app1": {
      "font": "large"
    }
  }
}

If you run the request again, the consolidated profile data is returned:

{
  "u_kd2JMqwUQwSCCOxMv7M1vw": {
    "uid": "u_kd2JMqwUQwSCCOxMv7M1vw",
    "enabled": true,
    "last_synchronized": 1642650651037,
    "user": {
      "username": "jacknich",
      "roles": [
        "admin", "other_role1"
      ],
      "realm_name": "native1",
      "full_name": "Jack Nicholson",
      "email": "jacknich@example.com"
    },
    "labels": {
      "app1": {
        "tag": "dev"
      }
    },
    "data": {
      "app1": {
        "theme": "default",
        "font": "large"
      }
    },
    "_doc": {
      "_primary_term": 1,
      "_seq_no": 0
    }
  }
}

« Suggest user profile API Snapshot and restore APIs »