access-api-keys.asciidoc

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.

{beatname_uc} instances typically send both collected data and monitoring information to {es}. If you are sending both to the same cluster, you can use the same API key. For different clusters, you need to use an API key per cluster.

Note	For security reasons, we recommend using a unique API key per {beatname_uc} instance. You can create as many API keys per user as necessary.

Create an API key for writing events

In {kib}, navigate to {stack-manage-app} > API keys and click Create API key.

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:

{
    "{beat_default_index_prefix}_writer": {
        "index": [
            {
                "names": ["{beat_default_index_prefix}-*"],
                "privileges": ["create_index", "create_doc"]
            }
        ]
    },
    "{beat_default_index_prefix}_sourcemap": {
        "index": [
            {
                "names": [".apm-source-map"],
                "privileges": ["read"]
            }
        ]
    },
    "{beat_default_index_prefix}_agentcfg": {
        "index": [
            {
                "names": [".apm-agent-configuration"],
                "privileges": ["read"]
            }
        ]
    }
}

Note	This example only provides privileges for writing data. See [feature-roles] for additional privileges and information.

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. In the dropdown, switch to {beats} and copy the API key.

You can now use this API key in your {beatname_lc}.yml configuration file:

output.elasticsearch:
  api_key: TiNAGG4BaaMdaH1tRfuU:KnR6yE41RrSowb0kQ0HWoA <1>

1. Format is id:api_key (as shown in the {beats} dropdown)

Create an API key for monitoring

In {kib}, navigate to {stack-manage-app} > API keys and click Create API key.

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:

{
    "{beat_default_index_prefix}_monitoring": {
        "index": [
            {
                "names": [".monitoring-beats-*"],
                "privileges": ["create_index", "create_doc"]
            }
      ]
    }
}

Note	This example only provides privileges for publishing monitoring data. See [feature-roles] for additional privileges and information.

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. In the dropdown, switch to {beats} and copy the API key.

You can now use this API key in your {beatname_lc}.yml configuration file like this:

monitoring.elasticsearch:
  api_key: TiNAGG4BaaMdaH1tRfuU:KnR6yE41RrSowb0kQ0HWoA <1>

1. Format is id:api_key (as shown in the {beats} dropdown)

Create an API key with {es} APIs

You can also use {es}'s {ref}/security-api-create-api-key.html[Create API key API] to create a new API key. For example:

POST /_security/api_key
{
  "name": "{beat_default_index_prefix}_host001", <1>
  "role_descriptors": {
    "{beat_default_index_prefix}_writer": { <2>
      "index": [
        {
          "names": ["{beat_default_index_prefix}-*"],
          "privileges": ["create_index", "create_doc"]
        }
      ]
    },
    "{beat_default_index_prefix}_sourcemap": {
      "index": [
        {
          "names": [".apm-source-map"],
          "privileges": ["read"]
        }
      ]
    },
    "{beat_default_index_prefix}_agentcfg": {
      "index": [
        {
          "names": [".apm-agent-configuration"],
          "privileges": ["read"]
        }
      ]
    }
  }
}

1. Name of the API key

2. Granted privileges, see [feature-roles]

See the {ref}/security-api-create-api-key.html[Create API key] reference for more information.

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]