This documentation supports an earlier version of BMC Helix Operations Management.To view the documentation for the latest version, select 23.3 from the Product version picker.

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 BMC Helix Operations Management. This API key is static and might get compromised if it is shared unintentionally, impacting the secure streaming of data to BMC Helix Operations Management. 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.

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.

Related topic

Using API keys for external integrations.

Troubleshooting-API-key-rotation-issues

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 BMC Helix Operations Management with BMC Helix IT Service Management 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 BMC Helix Portal 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 BMC Helix Portal. 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 BMC Helix Operations Management 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 BMC Helix Portal.

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  BMC Helix Operations Management:


To use the latest API key

After the API key is rotated in BMC Helix Portal, 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 BMC Helix Operations Management  by performing the following steps:

  1. Log in to BMC Helix Operations Management.
  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 BMC Helix Portal 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 BMC Helix Operations Management 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 BMC Helix Operations Management.
  2. Select Monitoring > Events.
  3. Verify if an information event is listed.
    This event is generated after the API key rotates in BMC Helix Portal.

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*