diff --git a/x-pack/docs/en/rest-api/security/create-api-keys.asciidoc b/x-pack/docs/en/rest-api/security/create-api-keys.asciidoc
index 84002f2e3fba7..a3dcb822ae4d5 100644
--- a/x-pack/docs/en/rest-api/security/create-api-keys.asciidoc
+++ b/x-pack/docs/en/rest-api/security/create-api-keys.asciidoc
@@ -75,7 +75,7 @@ authentication; it will not have authority to call {es} APIs.
 expire.
 
 `metadata`::
-(object) Arbitrary metadata that you want to associate with the API key.
+(Optional, object) Arbitrary metadata that you want to associate with the API key.
 It supports nested data structure.
 Within the `metadata` object, keys beginning with `_` are reserved for
 system usage.
diff --git a/x-pack/docs/en/rest-api/security/grant-api-keys.asciidoc b/x-pack/docs/en/rest-api/security/grant-api-keys.asciidoc
index 7b9727029adf4..e2df44b3fbf57 100644
--- a/x-pack/docs/en/rest-api/security/grant-api-keys.asciidoc
+++ b/x-pack/docs/en/rest-api/security/grant-api-keys.asciidoc
@@ -73,6 +73,12 @@ intersection of API keys permissions and the permissions of the user or access
 token. The structure of role descriptor is the same as the request for create
 role API. For more details, see <<security-api-put-role>>.
 
+`metadata`:::
+(Optional, object) Arbitrary metadata that you want to associate with the API key.
+It supports nested data structure.
+Within the `metadata` object, keys beginning with `_` are reserved for
+system usage.
+
 `grant_type`::
 (Required, string)
 The type of grant. Supported grant types are: `access_token`,`password`.
@@ -129,6 +135,14 @@ POST /_security/api_key/grant
           }
         ]
       }
+    },
+    "metadata": {
+      "application": "my-application",
+      "environment": {
+         "level": 1,
+         "trusted": true,
+         "tags": ["dev", "staging"]
+      }
     }
   }
 }