Grant access using API keys [beats-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.

Winlogbeat 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 Winlogbeat instance. You can create as many API keys per user as necessary. ::::

::::{important} Review Grant users access to secured resources before creating API keys for Winlogbeat. ::::

Create an API key for publishing [beats-api-key-publish]

To create an API key to use for writing data to {{es}}, use the Create API key API, for example:

console

POST /_security/api_key
{
  "name": "winlogbeat_host001", <1>
  "role_descriptors": {
    "winlogbeat_writer": { <2>
      "cluster": ["monitor", "read_ilm", "read_pipeline"],
      "index": [
        {
          "names": ["winlogbeat-*"],
          "privileges": ["view_index_metadata", "create_doc", "auto_configure"]
        }
      ]
    }
  }
}

Name of the API key
Granted privileges, see Grant users access to secured resources

::::{note} See Create a publishing user for the list of privileges required to publish events. ::::

The return value will look something like this:

console-result

{
  "id":"TiNAGG4BaaMdaH1tRfuU", <1>
  "name":"winlogbeat_host001",
  "api_key":"KnR6yE41RrSowb0kQ0HWoA" <2>
}

Unique id for this API key
Generated API key

You can now use this API key in your winlogbeat.yml configuration file like this:

yaml

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

Format is id:api_key (as returned by Create API key)

Create an API key for monitoring [beats-api-key-monitor]

To create an API key to use for sending monitoring data to {{es}}, use the Create API key API, for example:

console

POST /_security/api_key
{
  "name": "winlogbeat_host001", <1>
  "role_descriptors": {
    "winlogbeat_monitoring": { <2>
      "cluster": ["monitor"],
      "index": [
        {
          "names": [".monitoring-beats-*"],
          "privileges": ["create_index", "create"]
        }
      ]
    }
  }
}

Name of the API key
Granted privileges, see Grant users access to secured resources

::::{note} See Create a monitoring user for the list of privileges required to send monitoring data. ::::

The return value will look something like this:

console-result

{
  "id":"TiNAGG4BaaMdaH1tRfuU", <1>
  "name":"winlogbeat_host001",
  "api_key":"KnR6yE41RrSowb0kQ0HWoA" <2>
}

Unique id for this API key
Generated API key

You can now use this API key in your winlogbeat.yml configuration file like this:

yaml

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

Format is id:api_key (as returned by Create API key)

Learn more about API keys [learn-more-api-keys]

See the {{es}} API key documentation for more information: