Using API keys for external integrations

The API Keys use the apikey authentication and are regenerated at a specific interval. This type of key is used for external integrations and support only data ingestion use cases.

By default, the API key is automatically generated every 30 days and the default grace period is 15 days. After the valid period of 30 days, the API key will continue for a grace period of 15 days. With each rotation, a new API key is created, which is used for all future activities.

You can also manually generate the API key at any time. For example, when you suspect that the key is compromised or when you want to control the frequency of key rotation, you can manually generate a new key. At any given point, after the expiry of the grace period of old key, there will be only one active API key.

1. Navigate to the User access > Users and keys page. 
2. On the Access keys tab, click Add key.
3. Enter a name for the key. 
4. From the Key type list, select API.
5. (Optional) If you want a permanent API key, select Never rotate. For security reasons, we recommend that you create a key with a rotation interval.
   You can generate a new key any time by clicking Rotate now from the Key details pane.
6. Specify the rotation interval. The key rotation will take effect at UTC 00:00 regardless of the time the key was created.
7. Specify the grace period for this key. The grace period must be lesser than the rotation interval. The old key will be valid until the grace period expires. During the grace period, the old and new keys are active. After the grace period expires, the old key is deleted and only the new key is active. 
   For example, if you create an API key on Jan 1 with the rotation interval set to 30 days, and the grace period to 7 days. On Jan 31, a new API key is generated and the old key will be valid until Feb 6. The old key will expire on Feb 6, after which you will not be able to log in with this key.
   
8. Click Confirm. 
   
   

Example -  Changing the grace period

BMC Helix Operations Management has an API key that is used by multiple Patrol Agents. The key is set with a rotation interval of 30 days and grace period of 7 days. However, there are some activities to be done with the old key and it couldn't be completed within the grace period. In this case, you can extend the grace period to 15 days by completing the following steps:

1. Log in to BMC Helix Portal.

2. Navigate to User access > Users and keys page, and click the Access keys tab.

3. For the API key that you want to update, click Key details.
4. Edit the Key grace period field to 15. The key will be valid for 15 days from the start of the rotation interval.

Similarly, you can also reduce the grace period. When you want the old key that is in grace period to expire with immediate effect, in the Key details pane, click Rotate now. 

Managing API keys

Navigate to User access > Users and keys page, and click the Access keys tab. You can perform the following tasks from this page: