Fleet enrollment tokens

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 and which output to use. You can use the token as many times as needed. It remains valid until you revoke or delete it.

The enrollment token is used for the initial communication between Elastic Agent and Fleet Server. After the initial connection request from Elastic Agent, Fleet Server passes a communication API key to the agent. This API key includes only the necessary permissions to communicate with Fleet Server. If the API key is not valid, Fleet Server stops communicating with Elastic Agent.

Depending on the agent policy's output type, Fleet Server also passes additional data to Elastic Agent:

• For the Elasticsearch and remote Elasticsearch outputs, it passes 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 not valid, Elastic Agent stops ingesting data into Elasticsearch.

• For the Kafka output, it passes authentication parameters.

  The authentication parameters are defined in the authentication settings of the Kafka output and are used by Elastic Agent to authenticate with the Kafka cluster before sending data to it.

• For the Logstash output, it passes SSL/TLS configuration details.

  The SSL/TLS configuration details such as the SSL certificate authority, the SSL certificate, and the SSL certificate key are defined during Logstash output creation. Elastic Agent uses SSL/TLS client authentication to authenticate with the Logstash pipeline before sending data to it.

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

To create an enrollment token:

1. In Kibana, find Fleet in the navigation menu or use the global search field.

2. Open the Enrollment tokens tab, then click Create enrollment token.

3. Name your token and select an agent policy.

   The token name you specify must be unique to avoid conflict with any existing API keys.

4. Click Create enrollment token.

5. In the list of tokens, click the Show token icon to display the token secret.

All Elastic Agents enrolled with this token 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.

The Enrollment tokens tab provides controls to help you find specific tokens:

• Use the search bar to filter tokens using Kibana Query Language (KQL).
• Use the Agent policy dropdown to select one or more policies and show only tokens associated with those policies.
• Use the Active and Inactive filters to show tokens in that status. The Active filter is selected by default.

You can revoke an enrollment token that you no longer want to use to enroll Elastic Agents in an agent policy in Fleet. Revoking an enrollment token invalidates the API key, so you can no longer use this token to enroll agents. Agents that are already enrolled continue to function.

To revoke an enrollment token:

1. In Fleet, open the Enrollment tokens tab.

2. Locate the token you want to revoke. Use the filters if needed.

3. In the Actions column for the token:

   • Click the actions icon , then select Revoke.
   • Click the Revoke token icon .

4. In the confirmation dialog, confirm the action.

To revoke several tokens in a single operation, refer to Bulk revoke or delete enrollment tokens.

Revoking an enrollment token doesn't delete it immediately. Deletion occurs automatically after the duration specified in the Elasticsearch xpack.security.authc.api_key.delete.retention_period setting has expired. Refer to Invalidate API key API for details.

Until the enrollment token is deleted:

• The token name can't be reused when you create an enrollment token.
• You can still view the token in the Fleet UI.
• The token is returned by a GET /api/fleet/enrollment_api_keys API request. Revoked enrollment tokens are identified by "active": false.

Deleting an enrollment token invalidates the underlying API key and removes the token document from Elasticsearch.

To delete an enrollment token:

1. In Fleet, open the Enrollment tokens tab.
2. Locate the token to delete. Use the filters if needed.
3. In the Actions column for the token, click the actions icon , then select Delete token.
4. In the confirmation dialog, click Delete token.

To revoke or delete multiple enrollment tokens at the same time:

1. In Fleet, open the Enrollment tokens tab.
2. Use the filters to narrow the list, if needed.
3. Select the checkboxes for the tokens you want to manage. To select every token that matches the current filters, select the checkbox in the table header.
4. From the x tokens selected menu, select Revoke tokens or Delete tokens.
5. In the confirmation dialog, confirm the action.

A notification reports the number of tokens that were processed successfully and any errors that occurred. Tokens that belong to managed or agentless policies are skipped automatically.