Doc:Add info on using api keys for access Co-authored-by: João Duarte <jsvd@users.noreply.github.com>

docs/static/security/api-keys.asciidoc

@@ -2,8 +2,189 @@
 [[ls-api-keys]]
 ==== Grant access using API keys
 
-
 Instead of using usernames and passwords, you can use API keys to grant
 access to {es} resources. You can set API keys to expire at a certain time,
 and you can explicitly invalidate them. Any user with the `manage_api_key`
 or `manage_own_api_key` cluster privilege can create API keys.
+
+Note that API keys are tied to the cluster they are created in. If you are
+sending output to different clusters, be sure to create the correct kind of API
+key. 
+
+NOTE: For security reasons, we recommend using a unique API key per {ls} instance.
+You can create as many API keys per user as necessary.
+
+
+[float]
+[[ls-create-api-key]]
+===== Create an API key 
+
+You can create API keys using either the
+{ref}/security-api-create-api-key.html[Create API key API] or the
+{kibana-ref}/api-keys.html[Kibana UI]. This section walks you through creating
+an API key using the {ref}/security-api-create-api-key.html[Create API key API].
+The privileges needed are the same for either approach.
+
+Here is an example that shows how to create an API key for publishing to {es}
+using the <<plugins-outputs-elasticsearch,Elasticsearch output plugin>>.
+
+
+[source,console,subs="attributes,callouts"]
+------------------------------------------------------------
+POST /_security/api_key
+{
+  "name": "logstash_host001", <1>
+  "role_descriptors": {
+    "logstash_writer": { <2>
+      "cluster": ["monitor", "manage_ilm", "read_ilm"],
+      "index": [
+        {
+          "names": ["logstash-*"],
+          "privileges": ["view_index_metadata", "create_doc"]
+        }
+      ]
+    }
+  }
+}
+------------------------------------------------------------
+<1> Name of the API key
+<2> Granted privileges
+
+The return value should look similar to this:
+
+[source,console-result,subs="attributes,callouts"]
+--------------------------------------------------
+{
+  "id":"TiNAGG4BaaMdaH1tRfuU", <1>
+  "name":"logstash_host001",
+  "api_key":"KnR6yE41RrSowb0kQ0HWoA" <2>
+}
+--------------------------------------------------
+<1> Unique id for this API key
+<2> Generated API key
+
+
+[float]
+[[ls-api-key-publish]]
+====== Create an API key for publishing
+
+You're in luck! The example we used in the <<ls-create-api-key>> section creates
+an API key for publishing to {es} using the
+<<plugins-outputs-elasticsearch,Elasticsearch output plugin>>. 
+
+/////
+Work in Progress
+
+The API key for the Elasticsearch output plugin configuration requires these
+cluster privileges:
+
+* `monitor`
+* `manage_ilm`
+* `read_ilm`
+
+It requires these index privileges:
+
+* `view_index_metadata`
+* `create_doc`
+/////
+
+Here's an example using the API key in your
+<<plugins-outputs-elasticsearch,Elasticsearch output plugin>> configuration.
+
+["source","ruby"]
+-----
+output {
+  elasticsearch {
+    api_key => "TiNAGG4BaaMdaH1tRfuU:KnR6yE41RrSowb0kQ0HWoA" <1>
+  }
+}
+-----
+<1> Format is `id:api_key` (as returned by
+{ref}/security-api-create-api-key.html[Create API key])
+
+[float]
+[[ls-api-key-input]]
+====== Create an API key for reading
+
+Creating an API key to use for reading data from {es} is similar to creating an
+API key for publishing described earlier. You can use the example in the
+<<ls-create-api-key>> section, granting the appropriate privileges.
+
+/////
+Work in Progress
+The API key for the <<plugins-inputs-elasticsearch,Elasticsearch inputs plugin>>
+configuration requires these cluster privileges:
+
+* `monitor`
+* `read_ilm`
+
+It requires these index privileges:
+
+* `view_index_metadata`
+* `create_doc`
+/////
+
+Here's an example using the API key in your
+<<plugins-inputs-elasticsearch,Elasticsearch inputs plugin>> configuration.
+
+["source","ruby"]
+-----
+input {
+  elasticsearch {
+    "api_key" => "TiNAGG4BaaMdaH1tRfuU:KnR6yE41RrSowb0kQ0HWoA" <1>
+  }
+}
+-----
+<1> Format is `id:api_key` (as returned by
+{ref}/security-api-create-api-key.html[Create API key])s
+
+
+[float]
+[[ls-api-key-filter]]
+====== Create an API key for filtering
+
+Creating an API key to use for processing data from {es} is similar to creating
+an API key for publishing described earlier. You can use the example in the
+<<ls-create-api-key>> section, granting the appropriate privileges.
+
+/////
+Work in Progress
+
+The API key for the <<plugins-filters-elasticsearch,Elasticsearch filters plugin>>
+configuration requires these cluster privileges:
+
+* `monitor`
+* `read_ilm`
+
+It requires these index privileges:
+
+* `view_index_metadata`
+* `create_doc`
+/////
+
+Here's an example using the API key in your
+<<plugins-filters-elasticsearch,Elasticsearch filter plugin>> configuration.
+
+["source","ruby"]
+-----
+filter {
+  elasticsearch {
+    api_key => "TiNAGG4BaaMdaH1tRfuU:KnR6yE41RrSowb0kQ0HWoA" <1>
+  }
+}
+-----
+<1> Format is `id:api_key` (as returned by {ref}/security-api-create-api-key.html[Create API key])
+
+
+[float]
+[[learn-more-api-keys]]
+===== Learn more about API keys
+
+See the {es} API key documentation for more information:
+
+* {ref}/security-api-create-api-key.html[Create API key]
+* {ref}/security-api-get-api-key.html[Get API key information]
+* {ref}/security-api-invalidate-api-key.html[Invalidate API key]
+
+See {kibana-ref}/api-keys.html[API Keys] for info on managing API keys
+through {kib}.