[apm] Clarify how to create/use API keys

docs/en/observability/apm/configure/agent-config.asciidoc

@@ -21,8 +21,10 @@ Here's a sample configuration:
 [source,yaml]
 ----
 apm-server.agent.config.cache.expiration: 45s
-apm-server.agent.config.elasticsearch.api_key: TiNAGG4BaaMdaH1tRfuU:KnR6yE41RrSowb0kQ0HWoA
+apm-server.agent.config.elasticsearch.api_key: TiNAGG4BaaMdaH1tRfuU:KnR6yE41RrSowb0kQ0HWoA <1>
 ----
+<1> {blank}
+include::./outputs/elasticsearch.asciidoc[tag=configure-beats]
 
 [float]
 == APM agent configuration options
@@ -52,6 +54,9 @@ use these {es} options to provide {es} access.
 [float]
 === Common problems
 
+[float]
+==== HTTP 403 errors
+
 You may see either of the following HTTP 403 errors from APM Server when it attempts to fetch APM agent configuration:
 
 APM agent log:
@@ -72,3 +77,10 @@ This occurs because the user or API key set in either `apm-server.agent.config.e
 (if `apm-server.agent.config.elasticsearch` is not set) does not have adequate permissions to read source maps from {es}.
 
 To fix this error, ensure that APM Server has all the required privileges. See <<apm-privileges-agent-central-config-server>> for more details.
+
+[float]
+==== HTTP 401 errors
+
+If you get an HTTP 401 errors from APM Server, make sure you're using a token that you're using
+an API key that is configured to *Beats*. For details on how to create and configure a compatible
+API key, refer to <<apm-beats-api-key-publish>>.

docs/en/observability/apm/configure/outputs/elasticsearch.asciidoc

@@ -46,8 +46,10 @@ output.elasticsearch:
 ----
 output.elasticsearch:
   hosts: ["https://myEShost:9200"]
-  api_key: "ZCV7VnwBgnX0T19fN8Qe:KnR6yE41RrSowb0kQ0HWoA"
+  api_key: "ZCV7VnwBgnX0T19fN8Qe:KnR6yE41RrSowb0kQ0HWoA" <1>
 ----
+<1> {blank}
+include::elasticsearch.asciidoc[tag=configure-beats]
 
 *PKI certificate authentication:*
 
@@ -128,7 +130,13 @@ The default value is `false`.
 Instead of using a username and password, you can use API keys to secure communication
 with {es}. The value must be the ID of the API key and the API key joined by a colon: `id:api_key`.
 
-See <<apm-beats-api-keys>> for more information.
+// tag::configure-beats[]
+You _must_ set the API key to be configured to *Beats*.
+Base64 encoded API keys are not currently supported in this configuration.
+For details on how to create and configure a compatible API key, refer to <<apm-beats-api-key-publish>>.
+// end::configure-beats[]
+
+image::images/apm-api-key-beats.png[API key dropdown highlighting the Beats option]
 
 [float]
 ==== `username`

docs/en/observability/apm/https.asciidoc

@@ -37,7 +37,7 @@ output.elasticsearch:
   api_key: "KnR6yE41RrSowb0kQ0HWoA" <1>
 ----------------------------------------------------------------------
 <1> This API key must have the privileges required to publish events to {es}.
-To create an API key like this, see <<apm-beats-api-keys>>.
+include::./configure/outputs/elasticsearch.asciidoc[tag=configure-beats]
 --
 
 [[apm-beats-tls]]

docs/en/observability/apm/security/elastic-stack/access-api-keys.asciidoc

@@ -17,15 +17,17 @@ You can create as many API keys per user as necessary.
 [[apm-beats-api-key-publish]]
 == Create an API key for writing events
 
-To open **API keys**, find **Stack Management** in the main menu or use the {kibana-ref}/introduction.html#kibana-navigation-search[global search field].
-Click **Create API key**.
+To create an API key:
 
+. Go to **Stack Management** in the main menu and find **API Keys** or use the {kibana-ref}/introduction.html#kibana-navigation-search[global search field].
+. Click **Create API key**.
++
 [role="screenshot"]
 image::images/server-api-key-create.png[API key creation]
-
-Enter a name for your API key and select **Restrict privileges**.
++
+. Enter a name for your API key and select **Restrict privileges**.
 In the role descriptors box, assign the appropriate privileges to the new API key. For example:
-
++
 [source,json,subs="attributes,callouts"]
 ----
 {
@@ -57,16 +59,19 @@ In the role descriptors box, assign the appropriate privileges to the new API ke
     }
 }
 ----
-
++
 NOTE: This example only provides privileges for **writing data**.
 See <<apm-feature-roles>> for additional privileges and information.
-
-To set an expiration date for the API key, select **Expire after time**
++
+. To set an expiration date for the API key, select **Expire after time**
 and input the lifetime of the API key in days.
+. Click **Create API key**.
+. {blank}
+include::../../configure/outputs/elasticsearch.asciidoc[tag=configure-beats]
++
+image::images/apm-api-key-beats.png[API key dropdown highlighting the Beats option]
 
-Click **Create API key**. In the dropdown, switch to **{beats}** and copy the API key.
-
-You can now use this API key in your +apm-server.yml+ configuration file:
+You can now use this API key in your `apm-server.yml` configuration file:
 
 ["source","yml",subs="attributes"]
 --------------------