IMPORTANT: No additional bug fixes or documentation updates will be released for this version. For the latest information, see the current release documentation.
Elastic Docs › ›Secure communication with APM agents
« APM agent TLS communication Secret token »

API keysedit

API keys are sent as plain-text, so they only provide security when used in combination with TLS.

Enable API key authorization in the APM integration settings. When enabled, API keys are used to authorize requests to the APM Server.

You can assign one or more unique privileges to each API key:

  • Agent configuration (config_agent:read): Required for agents to read Agent configuration remotely.
  • Ingest (event:write): Required for ingesting agent events.

To secure the communication between APM Agents and the APM Server with API keys, make sure TLS is enabled, then complete these steps:

  1. Enable API keys
  2. Create an API key user
  3. Create an API key in Kibana
  4. Set the API key in your APM agents

Enable API keysedit

Enable API key authorization in the APM integration settings. You should also set a limit on the number of unique API keys that APM Server allows per minute; this value should be the number of unique API keys configured in your monitored services.

Create an API key user in Kibanaedit

API keys can only have the same or lower access rights than the user that creates them. Instead of using a superuser account to create API keys, you can create a role with the minimum required privileges.

The user creating an APM agent API key must have at least the manage_own_api_key cluster privilege and the APM application-level privileges that it wishes to grant. In addition, when creating an API key from the APM app, you’ll need the appropriate Kibana Space and Feature privileges.

The example below uses the Kibana role management API to create a role named apm_agent_key_role.

POST /_security/role/apm_agent_key_role
{
   "cluster": [ "manage_own_api_key" ],
   "applications": [
      {
         "application":"apm",
         "privileges":[
            "event:write",
            "config_agent:read",
            "sourcemap:write"
         ],
         "resources":[ "*" ]
      },
      {
         "application":"kibana-.kibana",
         "privileges":[ "feature_apm.all" ],
         "resources":[ "space:default" ] 
      }
   ]
}

This example assigns privileges for the default space.

Assign the newly created apm_agent_key_role role to any user that wishes to create APM agent API keys.

Create an API key in the APM appedit

The APM app has a built-in workflow that you can use to easily create and view APM agent API keys. Only API keys created in the APM app will show up here.

Using a superuser account, or a user with the role created in the previous step, open Kibana and navigate to Observability > APM > Settings > Agent keys. Enter a name for your API key and select at least one privilege.

For example, to create an API key that can be used to ingest APM events and read agent central configuration, select config_agent:read and event:write.

The sourcemap:write privilege is outdated and will be removed in a future release. To learn more about the privileges required to upload a source map, see the RUM source map API.

Click Create APM Agent key and copy the Base64 encoded API key. You will need this for the next step, and you will not be able to view it again.

APM app API key

Set the API key in your APM agentsedit

You can now apply your newly created API keys in the configuration of each of your APM agents. See the relevant agent documentation for additional information:

« APM agent TLS communication Secret token »