Default language.

Using rotating API keys for secure data streaming

An API key is used for metric ingestion from PATROL Agents, event and log ingestion from event and log sources, and for third-party integrations. PATROL Agents use the API key to authenticate themselves when they send messages to . This API key is static and might get compromised if it is shared unintentionally, impacting the secure streaming of data to . You can set up configurations to rotate the API key. The API key rotates after a specific interval and is pushed to PATROL Agents through a monitor policy. 

Rotating API keys ensure secure data streaming because even if unauthorized users get access to the key, the compromised key will be invalid when the key rotates and a new key is generated.

Related topic

Using API keys for external integrations.

Troubleshooting-API-key-rotation-issues

The API Key format is subject to change, but its format does not affect the functionality. For more information about the API key format, see Support for HTTP communication.

The API keys are granted the following permissions by default:

  • core.events.ingest
  • core.metrics.ingest

If  is enabled, the loganalytics.logs.ingest permission is also granted by default to API keys.

Scenario

Sarah is an administrator at Apex Global. Her organization has been using static API keys for metric, event, and log ingestion from PATROL Agents. A user unintentionally shares the static API key and the secure data streaming is compromised. To keep their systems secure, they now want to use an API key that rotates after a specific interval so that the metric, event, and log ingestion from PATROL Agents is secure.


To use rotating API keys

Important

If you use third-party integrations or integrate  with  for incident creation, make sure that you update the API key in the integrations with the rotated API key within the grace period. This update is required each time the API key rotates for the integrations to work seamlessly.

For more information, see Configuring the connectors for Proactive Service Resolution.

Refer to the following table for instructions on using rotating API keys:


To enable the API key rotation

  1. Log in to  and select User Access > Users and keys.
  2. On the Access keys tab, locate the key with Key type as API and Key name in the tenant_id@timestamp format.
    The API key is created when a tenant is onboarded to . You cannot delete the out-of-box API key that is created during the tenant onboarding process. By default the API key rotation value is set to Never rotates.
  3. Select Actions > Key details.
  4. Click Edit schedule.
  5. Clear the Disable rotation check box and specify the Rotation interval and the Key grace period.
  6. Click Confirm.

The feature to use rotated API keys in  is not enabled and the static API key is used until the rotation period is changed from Never rotates (default value) to a desired key rotation interval in .

Best practice

  • We recommend that you set the API key rotation interval to 30 days and the default grace period to 15 days.
  • We do not recommend that you set the API key rotation interval to 1 day.


To verify the API key rotation

Refer to the following table for instructions on verifying that the key rotation is enabled in  :


To use the latest API key

After the API key is rotated in , make sure that you use the latest API key when you deploy packages to PATROL Agents.

For more information, see the following topics:

In addition to deploying packages, if you use the API key to authenticate API URLs and deploy the BMC Helix Monitor Agent, make sure that you use the latest API key each time the key rotates.
For more information, see the following topics:


To restart the PATROL Agent

If the PATROL Agent version is earlier than 23.1, restart the PATROL Agents within the grace period to use the rotated API key.

PATROL Agents version 23.1 or later use the rotated API key and don't require a restart.

Warning

If you do not restart PATROL Agents that have versions earlier than 23.1 within the grace period, the PATROL Agents disconnect and stop collecting data.

For information about restarting PATROL Agents, see the following topics:


To view the monitor policy

View the Policy for rotated API key push policy to verify that the policy uses the rotated API key value in   by performing the following steps:

  1. Log in to .
  2. Select Configuration > Monitor Policies.
  3. Verify if the Policy for rotated API key push is listed.
    This policy is listed after the API key is enabled by setting a rotation interval (interval changed from Never rotates to desired key rotation interval) in  and pushes the rotated API key to all PATROL Agents.

Important

This is a read-only policy and hence can only be viewed.

Monitor policies list.png

For more information, see Defining-monitor-policies.


To view the event

The information event in  notifies users about the key rotation, indicates that all PATROL Agents are connected, and the rotated API key can be pushed to PATROL Agents.

  1. Log in to .
  2. Select Monitoring > Events.
  3. Verify if an information event is listed.
    This event is generated after the API key rotates in .

Important

Ensure that the rotated API key is pushed within the grace period to avoid the following situations:

  • PATROL Agents getting disconnected.
  • Manually updating the rotated API key on PATROL Agents.

Information event on events page.png


 

Tip: For faster searching, add an asterisk to the end of your partial query. Example: cert*