IMPORTANT: No additional bug fixes or documentation updates will be released for this version. For the latest information, see the current release documentation.
« Required roles and privileges Kibana Fleet APIs »
Elastic Docs ›Fleet and Elastic Agent Guide [8.15] ›Centrally manage Elastic Agents in Fleet

Fleet enrollment tokens

edit

Fleet enrollment tokens

edit

A Fleet enrollment token (referred to as an enrollment API key in the Fleet API documentation) is an Elasticsearch API key that you use to enroll one or more Elastic Agents in Fleet. The enrollment token enrolls the Elastic Agent in a specific agent policy that defines the data to be collected by the agent. You can use the token as many times as required. It will remain valid until you revoke it.

The enrollment token is used for the initial communication between Elastic Agent and Fleet Server. After the initial connection request from the Elastic Agent, the Fleet Server passes two API keys to the Elastic Agent:

  • An output API key

    This API key is used to send data to Elasticsearch. It has the minimal permissions needed to ingest all the data specified by the agent policy. If the API key is invalid, the Elastic Agent stops ingesting data into Elasticsearch.

  • A communication API key

    This API key is used to communicate with the Fleet Server. It has only the permissions needed to communicate with the Fleet Server. If the API key is invalid, Fleet Server stops communicating with the Elastic Agent.

Create enrollment tokens

edit

Create enrollment tokens and use them to enroll Elastic Agents in specific policies.

When you use the Fleet UI to add an agent or create a new policy, Fleet creates an enrollment token for you automatically.

To create an enrollment token:

  1. In Kibana, go to Management → Fleet → Enrollment tokens.

  2. Click Create enrollment token. Name your token and select an agent policy.

    Note that the token name you specify must be unique so as to avoid conflict with any existing API keys.

    Enrollment tokens tab in Fleet
  3. Click Create enrollment token.

  4. In the list of tokens, click the Show token icon to see the token secret.

    Enrollment tokens tab with Show token icon highlighted

All Elastic Agents enrolled through this token will use the selected policy unless you assign or enroll them in a different policy.

To learn how to install Elastic Agents and enroll them in Fleet, refer to Install Elastic Agents.

You can use the Fleet API to get a list of enrollment tokens. For more information, refer to Kibana Fleet APIs.

Revoke enrollment tokens

edit

You can revoke an enrollment token that you no longer wish to use to enroll Elastic Agents in an agent policy in Fleet. Revoking an enrollment token essentially invalidates the API key used by agents to communicate with Fleet Server.

To revoke an enrollment token:

  1. In Fleet, click Enrollment tokens.

  2. Find the token you want to revoke in the list and click the Revoke token icon.

    Enrollment tokens tab with Revoke token highlighted

  3. Click Revoke enrollment token. You can no longer use this token to enroll Elastic Agents. However, the currently enrolled agents will continue to function.

    To re-enroll your Elastic Agents, use an active enrollment token.

Note that when an enrollment token is revoked it is not immediately deleted. Deletion occurs automatically after the duration specified in the Elasticsearch xpack.security.authc.api_key.delete.retention_period setting has expired (see Invalidate API key API for details).

Until the enrollment token has been deleted:

  • The token name may not be re-used when you create an enrollment token.
  • The token continues to be visible in the Fleet UI.
  • The token continues to be returned by a GET /api/fleet/enrollment_api_keys API request. Revoked enrollment tokens are identified as "active": false.
« Required roles and privileges Kibana Fleet APIs »