From e6d50ffb189aaf3510f49d48402dbb90cb016fec Mon Sep 17 00:00:00 2001
From: Yogesh Gaikwad <902768+bizybot@users.noreply.github.com>
Date: Fri, 23 Aug 2019 20:17:54 +1000
Subject: [PATCH] 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
---
 .../rest-api/security/get-api-keys.asciidoc   | 44 +++++++++++++++++--
 .../security/invalidate-api-keys.asciidoc     | 39 ++++++++++++++--
 2 files changed, 77 insertions(+), 6 deletions(-)

diff --git a/x-pack/docs/en/rest-api/security/get-api-keys.asciidoc b/x-pack/docs/en/rest-api/security/get-api-keys.asciidoc
index 7201a3f324d0e..1aa47ebab64cc 100644
--- a/x-pack/docs/en/rest-api/security/get-api-keys.asciidoc
+++ b/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:
 
diff --git a/x-pack/docs/en/rest-api/security/invalidate-api-keys.asciidoc b/x-pack/docs/en/rest-api/security/invalidate-api-keys.asciidoc
index a5cdcb1821e81..ecd79a0906cfd 100644
--- a/x-pack/docs/en/rest-api/security/invalidate-api-keys.asciidoc
+++ b/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: