Link Search Menu Expand Document Documentation Menu

Patch Users API

Introduced 1.0

Updates internal users without replacing them. Specify a user name to update individual attributes of one user, or omit the user name to create, update, or delete multiple users in a single call.

Endpoints

PATCH /_plugins/_security/api/internalusers
PATCH /_plugins/_security/api/internalusers/{username}

Path parameters

The following table lists the available path parameters.

Parameter Data type Required Description
username String No The name of the user to update. If omitted, the request can modify multiple users.

Query parameters

The following table lists the available query parameters. All query parameters are optional.

Parameter Data type Description
wait_for_completion Boolean Whether to wait for the configuration write and reload to complete. When false, the API returns a task ID after validation. Default is true.

Request body fields

The request body is required. It is an array of JSON objects. Each object contains the following fields.

Field Data type Description Required
op String The operation to perform. Valid values are add, remove, replace, move, copy, and test. Yes
path String The path to modify. When you specify a user name, the path is relative to that user, such as /backend_roles. When you omit the user name, the path names the user, such as /spock. Yes
value Object The new value. Required for the add, replace, and test operations. No

Example request

The following request updates the backend roles of the kirk user:

PATCH _plugins/_security/api/internalusers/kirk
[
  {
    "op": "replace",
    "path": "/backend_roles",
    "value": [
      "commander"
    ]
  }
]

The following request adds the spock and worf users and removes the riker user:

PATCH _plugins/_security/api/internalusers
[
  {
    "op": "add",
    "path": "/spock",
    "value": {
      "password": "Str0ngPassw0rd_7741!",
      "backend_roles": [
        "science"
      ]
    }
  },
  {
    "op": "add",
    "path": "/worf",
    "value": {
      "password": "Str0ngPassw0rd_3390!",
      "backend_roles": [
        "security"
      ]
    }
  },
  {
    "op": "remove",
    "path": "/riker"
  }
]

Example response

When you update one user, the response contains the user name:

{
  "status": "OK",
  "message": "'kirk' updated."
}

When you update multiple users, the response appears as follows:

{
  "status": "OK",
  "message": "Resource updated."
}

If you set wait_for_completion to false, a successful submission returns HTTP status 200, and the response contains a task ID instead of the completed result:

{
  "task": "oTUltX4IQMOUUVeiohTt8A:1234"
}

Use the Get Task API to retrieve the task’s status and result. For more information, see Using wait_for_completion for configuration changes.

350 characters left

Have a question? .

Want to contribute? or .

⌂ 换网址