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.

To create an 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 key.
  5. (Optional) If you want a permanent API key, select Disable rotation.
    For security reasons, we recommend that you create a key with a rotation interval. You can generate a new key any time by using the Rotate now or Edit schedule options from the Key details pane.
  6. (Optional) By default, an API key can be deleted, so to prevent a key from getting deleted, select Disable deletion.
    You cannot disable the delete option of an API key after it is created.

  7. Specify the rotation interval. The key rotation will take effect at UTC 00:00 regardless of the time the key was created.
  8. 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.
  9. Click Confirm

Can I modify an API key?

Yes, you can modify the details of an API key by using the Actions > Key details option. However, if an API key is disabled for deletion, you cannot modify the name of the key. 

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:

TaskProcedure

Copy key details

Copies the tenant ID, access key, and secret key. You can use the key details to access the APIs.

To use the old keys: If the old key is in the grace period, the Old key tab is enabled. Click Copy old key details. After the expiry of grace period, you cannot access the Old key tab.

The keys are copied in the following format: api key:<access key>::<secret key>,tenant id: <tenant ID>

Change the rotation schedule of a key

  • Although not recommended, you can choose to use a same API key always by setting the key to Never rotate.
  • To manually generate a key any time, click Rotate now. For example, if you want a new key before the scheduled rotate interval, you can manually change the key. 
  • To edit the rotation interval and grace period, use the Rotation interval and Key grace period options.

Delete a key

  1. From the Actions menu, select Delete.

  2. To confirm the deletion, click Delete key.
    When you delete a key, any functionality associated with the key will not work as the key will be permanently deleted. 

Was this page helpful? Yes No Submitting... Thank you

Comments