[DOCS] Update API key API

x-pack/docs/en/rest-api/security/create-api-keys.asciidoc

@@ -50,7 +50,7 @@ The following parameters can be specified in the body of a POST or PUT request:
 
 [[api-key-role-descriptors]]
 `role_descriptors`::
-(Optional, array-of-role-descriptor) An array of role descriptors for this API
+(Optional, object) The role descriptors for this API
 key. This parameter is optional. When it is not specified or is an empty array,
 then the API key will have a _point in time snapshot of permissions of the
 authenticated user_. If you supply role descriptors then the resultant permissions
@@ -144,7 +144,7 @@ API key information.
 <1> Unique `id` for this API key
 <2> Optional expiration in milliseconds for this API key
 <3> Generated API key
-<4> API key credentials which is the Base64-encoding of the UTF-8 
+<4> API key credentials which is the Base64-encoding of the UTF-8
 representation of the `id` and `api_key` joined by a colon (`:`).
 
 To use the generated API key, send a request with an `Authorization` header that

x-pack/docs/en/rest-api/security/grant-api-keys.asciidoc

@@ -70,7 +70,7 @@ expire.
 (Required, string) Specifies the name for this API key.
 
 `role_descriptors`:::
-(Optional, array-of-role-descriptor) An array of role descriptors for this API
+(Optional, object) The role descriptors for this API
 key. This parameter is optional. When it is not specified or is an empty array,
 the API key has a point in time snapshot of permissions of the specified user or
 access token. If you supply role descriptors, the resultant permissions are an

x-pack/docs/en/rest-api/security/update-api-key.asciidoc

@@ -1,5 +1,275 @@
 [role="xpack"]
 [[security-api-update-api-key]]
-=== Update API key information API
+=== Update API key API
 
-coming::[8.4.0]
+++++
+<titleabbrev>Update API key</titleabbrev>
+++++
+
+[[security-api-update-api-key-request]]
+==== {api-request-title}
+
+`PUT /_security/api_key/<id>`
+
+[[security-api-update-api-key-prereqs]]
+==== {api-prereq-title}
+
+* To use this API, you must have at least the `manage_own_api_key` cluster privilege.
+Users can only update API keys that they created or that were granted to them.
+To update another user's API key, use the <<run-as-privilege,`run_as` feature>>
+to submit a request on behalf of another user.
+
+IMPORTANT: It's not possible to use an API key as the authentication credential for this API.
+To update an API key, the owner user's credentials are required.
+
+[[security-api-update-api-key-desc]]
+==== {api-description-title}
+
+Use this API to update API keys created by the <<security-api-create-api-key,create API Key>> or <<security-api-grant-api-key,grant API Key>> APIs.
+It's not possible to update expired API keys, or API keys that have been invalidated by <<security-api-invalidate-api-key,invalidate API Key>>.
+
+This API supports updates to an API key's access scope and metadata.
+The access scope of an API key is derived from the <<security-api-update-api-key-api-key-role-descriptors,`role_descriptors`>> you specify in the request, and a snapshot of the owner user's permissions at the time of the request.
+The snapshot of the owner's permissions is updated automatically on every call.
+
+[IMPORTANT]
+====
+If you don't specify <<security-api-update-api-key-api-key-role-descriptors,`role_descriptors`>> in the request, a call to this API might still change the API key's access scope.
+This change can occur if the owner user's permissions have changed since the API key was created or last modified.
+====
+
+[[security-api-update-api-key-path-params]]
+==== {api-path-parms-title}
+
+`id`::
+(Required, string) The ID of the API key to update.
+
+[[security-api-update-api-key-request-body]]
+==== {api-request-body-title}
+
+You can specify the following parameters in the request body, which is optional.
+
+[[security-api-update-api-key-api-key-role-descriptors]]
+`role_descriptors`::
+(Optional, object) The role descriptors to assign to this API key.
+The API key's effective permissions are an intersection of its assigned privileges and the point in time snapshot of permissions of the owner user.
+If no privileges are assigned, the API key inherits the owner user's full permissions.
+You can assign new privileges to the API key by specifying them in this parameter.
+To remove assigned privileges, you can supply an empty `role_descriptors` parameter.
+The snapshot of the owner's permissions is always updated, whether you supply the `role_descriptors` parameter or not.
+The structure of a role descriptor is the same as the request for the <<security-api-put-role, create or update roles API>>.
+
+`metadata`::
+(Optional, object) Arbitrary metadata that you want to associate with the API key.
+It supports nested data structure.
+Within the `metadata` object, top-level keys beginning with `_` are reserved for system usage.
+When specified, this fully replaces metadata previously associated with the API key.
+
+[[security-api-update-api-key-response-body]]
+==== {api-response-body-title}
+
+`updated`::
+(boolean) If `true`, the API key was updated.
+If `false`, the API key didn't change because no change was detected.
+
+[[security-api-update-api-key-example]]
+==== {api-examples-title}
+
+If you create an API key as follows:
+
+[source,console]
+------------------------------------------------------------
+POST /_security/api_key
+{
+  "name": "my-api-key",
+  "role_descriptors": {
+    "role-a": {
+      "cluster": ["all"],
+      "index": [
+        {
+          "names": ["index-a*"],
+          "privileges": ["read"]
+        }
+      ]
+    }
+  },
+  "metadata": {
+    "application": "my-application",
+    "environment": {
+       "level": 1,
+       "trusted": true,
+       "tags": ["dev", "staging"]
+    }
+  }
+}
+------------------------------------------------------------
+
+A successful call returns a JSON structure that provides API key information.
+For example:
+
+[source,console-result]
+--------------------------------------------------
+{
+  "id": "VuaCfGcBCdbkQm-e5aOx",
+  "name": "my-api-key",
+  "api_key": "ui2lp2axTNmsyakw9tvNnw",
+  "encoded": "VnVhQ2ZHY0JDZGJrUW0tZTVhT3g6dWkybHAyYXhUTm1zeWFrdzl0dk5udw=="
+}
+--------------------------------------------------
+// TESTRESPONSE[s/VuaCfGcBCdbkQm-e5aOx/$body.id/]
+// TESTRESPONSE[s/ui2lp2axTNmsyakw9tvNnw/$body.api_key/]
+// TESTRESPONSE[s/VnVhQ2ZHY0JDZGJrUW0tZTVhT3g6dWkybHAyYXhUTm1zeWFrdzl0dk5udw==/$body.encoded/]
+
+For the examples below, assume that the owner user's permissions are:
+
+[[security-api-update-api-key-examples-user-permissions]]
+[source,js]
+--------------------------------------------------
+{
+  "cluster": ["all"],
+  "index": [
+    {
+      "names": ["*"],
+      "privileges": ["all"]
+    }
+  ]
+}
+--------------------------------------------------
+// NOTCONSOLE
+
+The following example updates the API key created above, assigning it new role descriptors and metadata:
+
+[source,console]
+----
+PUT /_security/api_key/VuaCfGcBCdbkQm-e5aOx
+{
+  "role_descriptors": {
+    "role-a": {
+      "index": [
+        {
+          "names": ["*"],
+          "privileges": ["write"]
+        }
+      ]
+    }
+  },
+  "metadata": {
+    "environment": {
+       "level": 2,
+       "trusted": true,
+       "tags": ["production"]
+    }
+  }
+}
+----
+// TEST[s/VuaCfGcBCdbkQm-e5aOx/\${body.id}/]
+// TEST[continued]
+
+A successful call returns a JSON structure indicating that the API key was updated:
+
+[source,console-result]
+----
+{
+  "updated": true
+}
+----
+
+The API key's effective permissions after the update will be the intersection of the supplied role descriptors and the <<security-api-update-api-key-examples-user-permissions, owner user's permissions>>:
+
+[source,js]
+--------------------------------------------------
+{
+  "index": [
+    {
+      "names": ["*"],
+      "privileges": ["write"]
+    }
+  ]
+}
+--------------------------------------------------
+// NOTCONSOLE
+
+The following example removes the API key's previously assigned permissions.
+
+[source,console]
+----
+PUT /_security/api_key/VuaCfGcBCdbkQm-e5aOx
+{
+  "role_descriptors": {}
+}
+----
+// TEST[skip:api key id not available anymore]
+
+Which returns the response:
+
+[source,console-result]
+----
+{
+  "updated": true
+}
+----
+
+The API key's effective permissions after the update will the same as the <<security-api-update-api-key-examples-user-permissions, owner user's>>:
+
+[source,js]
+--------------------------------------------------
+{
+  "cluster": ["all"],
+  "index": [
+    {
+      "names": ["*"],
+      "privileges": ["all"]
+    }
+  ]
+}
+--------------------------------------------------
+// NOTCONSOLE
+
+For the next example, assume that the owner user's permissions have changed from <<security-api-update-api-key-examples-user-permissions, the original permissions>> to:
+
+[source,js]
+--------------------------------------------------
+{
+  "cluster": ["manage_security"],
+  "index": [
+    {
+      "names": ["*"],
+      "privileges": ["read"]
+    }
+  ]
+}
+--------------------------------------------------
+// NOTCONSOLE
+
+The following request auto-updates the snapshot of the user's permissions associated with the API key:
+
+[source,console]
+----
+PUT /_security/api_key/VuaCfGcBCdbkQm-e5aOx
+----
+// TEST[skip:api key id not available anymore]
+
+Which returns the response:
+
+[source,console-result]
+----
+{
+  "updated": true
+}
+----
+
+Resulting in the following effective permissions for the API key:
+
+[source,js]
+--------------------------------------------------
+{
+  "cluster": ["manage_security"],
+  "index": [
+    {
+      "names": ["*"],
+      "privileges": ["read"]
+    }
+  ]
+}
+--------------------------------------------------
+// NOTCONSOLE