Document API key API changes for owner flag (#45698)

This commit adds documentation for owner flag
for API key APIs. By default, this flag is false
and when set to true restrict the API key operations
to the API keys owned by the currently authenticated
user.

Relates: #40031

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

@@ -39,13 +39,20 @@ pertain to retrieving api keys:
 
 `realm_name`::
 (Optional, string) The name of an authentication realm. This parameter cannot be
-used with either `id` or `name`.
+used with either `id` or `name` or when `owner` flag is set to `true`.
 
 `username`::
 (Optional, string) The username of a user. This parameter cannot be used with
-either `id` or `name`.
+either `id` or `name` or when `owner` flag is set to `true`.
 
-NOTE: While all parameters are optional, at least one of them is required.
+`owner`::
+(Optional, boolean) A boolean flag that can be used to query API keys owned
+by the currently authenticated user. Defaults to false. 
+The 'realm_name' or 'username' parameters cannot be specified when this
+parameter is set to 'true' as they are assumed to be the currently authenticated ones.
+
+NOTE: At least one of "id", "name", "username" and "realm_name" must be specified
+ if "owner" is "false" (default).
 
 [[security-api-get-api-key-example]]
 ==== {api-examples-title}
@@ -114,6 +121,37 @@ GET /_security/api_key?username=myuser
 // CONSOLE
 // TEST[continued]
 
+The following example retrieves all API keys owned by the currently authenticated user:
+
+[source,js]
+--------------------------------------------------
+GET /_security/api_key?owner=true
+--------------------------------------------------
+// CONSOLE
+// TEST[continued]
+
+Following creates an API key
+
+[source, js]
+------------------------------------------------------------
+POST /_security/api_key
+{
+  "name": "my-api-key-1"
+}
+------------------------------------------------------------
+// CONSOLE
+
+The following example retrieves the API key identified by the specified `id` if
+it is owned by the currently authenticated user:
+
+[source,js]
+--------------------------------------------------
+GET /_security/api_key?id=VuaCfGcBCdbkQm-e5aOx&owner=true
+--------------------------------------------------
+// CONSOLE
+// TEST[s/VuaCfGcBCdbkQm-e5aOx/$body.id/]
+// TEST[continued]
+
 Finally, the following example retrieves all API keys for the user `myuser` in
  the `native1` realm immediately:
 

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

@@ -40,13 +40,20 @@ pertain to invalidating api keys:
 
 `realm_name`::
 (Optional, string) The name of an authentication realm. This parameter cannot be
-used with either `id` or `name`.
+used with either `id` or `name` or when `owner` flag is set to `true`.
 
 `username`::
 (Optional, string) The username of a user. This parameter cannot be used with
-either `id` or `name`.
+either `id` or `name` or when `owner` flag is set to `true`.
 
-NOTE: While all parameters are optional, at least one of them is required.
+`owner`::
+(Optional, boolean) A boolean flag that can be used to query API keys owned
+by the currently authenticated user. Defaults to false.
+The 'realm_name' or 'username' parameters cannot be specified when this
+parameter is set to 'true' as they are assumed to be the currently authenticated ones.
+
+NOTE: At least one of "id", "name", "username" and "realm_name" must be specified
+ if "owner" is "false" (default).
 
 [[security-api-invalidate-api-key-response-body]]
 ==== {api-response-body-title}
@@ -138,6 +145,32 @@ DELETE /_security/api_key
 // CONSOLE
 // TEST
 
+The following example invalidates the API key identified by the specified `id` if
+ it is owned by the currently authenticated user immediately:
+
+[source,js]
+--------------------------------------------------
+DELETE /_security/api_key
+{
+  "id" : "VuaCfGcBCdbkQm-e5aOx",
+  "owner" : "true"
+}
+--------------------------------------------------
+// CONSOLE
+
+The following example invalidates all API keys owned by the currently authenticated
+ user immediately:
+
+[source,js]
+--------------------------------------------------
+DELETE /_security/api_key
+{
+  "owner" : "true"
+}
+--------------------------------------------------
+// CONSOLE
+// TEST
+
 Finally, the following example invalidates all API keys for the user `myuser` in
  the `native1` realm immediately: