How to utilize the IBM Cloud IAM Identity Services API to clean up inactive API keys and service IDs for improved account security.

If you have a good overview of all the service IDs and API keys in your IBM Cloud account, you can skip reading this blog post. If not, you are probably like us — sometimes wondering what resources, identities and API keys were created while working on a project. Creating is easy, but keeping tabs on resources and cleaning up is a chore, with no fun involved. So it was great to learn about some API functions that help to clean up an account and, thereby, enhance security.

In this blog post, we take a look at the IBM Cloud IAM (Identity and Access Management) Identity Services API. It provides functions to manage API keys and tokens, service IDs and trusted profiles, and it provides activity reports to identify inactive identities. We show how you can either create your own reports to identify unused API keys and identities or utilize the reporting feature (including the one integrated into the IBM Cloud console, as shown in the following screenshot):

IBM Cloud report on inactive identities showing recently used API keys.

IAM Identity Services API

IBM Cloud Identity and Access Management (IAM) authenticates (identifies) users who can access IBM Cloud and controls access to the resources. The IAM Identity Services API can be used to manage API keys and create access tokens. It also provides functions to manage service IDs and trusted profiles. Another function, which was added earlier this year, is the ability to trigger and retrieve activity reports for the account. The latter allows security administrators to identify inactive identities. Interestingly, you can build the same type of report yourself by utilizing other functions offered by the IAM Identity Services API:

  • Get API keys: This function allows you to retrieve all API keys for a given service ID, user ID or for the entire account. To operate on the account level, you need administrator privileges. The function returns all the API keys in scope (including API keys for service IDs) but not the activity details.
  • Get details of an API key: By requesting the activity data be included, the details show how many times the API key was used and when it was used last. This allows you to determine if the API key is actively used or can be deleted (see screenshot below).
  • List service IDs: This function allows you to retrieve a list of all (accessible) service IDs. Similar to the API keys function, no activity data is included, but it can be requested for individual service IDs using the following function.
  • Get details of a service ID: The details for a service ID include information on its API keys. With the optional parameter to request activity data, the usage count and (if available) the last authentication timestamp are included. Note that service IDs do not authenticate, but their API keys do.
  • List trusted profiles: This function will give you a list of all trusted profiles in the account.
  • Get a trusted profile: This allows you to get a trusted profile with the additional parameter to include activity data to check if it was recently used. Trusted profiles do not have any associated API keys, but compute identities or federated identities.
  • It’s not part of the IAM Identity Services, but the User Management APIs are functions to list users in the account and to access individual user profile data. Again, it is possible to request activity data.

You can use the above functions to build your own report or reporting tool to investigate inactive or infrequently used identities. However, the IAM Identity Services API offers functions to trigger and retrieve an official report. You’ll need special privileges to work with them:

  • Trigger a report: This kicks off the report generation. You can specify how many hours back the duration should be. By default, the report considers a duration of 720 hours. The request comes back with a report ID to be used with the retrieval function.
  • Get activity report: When calling this function, either a unique report ID or just “latest” can be specified. The report includes activity details for users, API keys, service IDs and trusted profiles. If the requested report is not available yet, it returns a status of 204.

Note that all operations related to retrieving activity data are expensive and take longer. Hence, they should only be exercised when necessary:

Request details for an IBM Cloud API key, including activity data.

Exercise the APIs

Now that we have a good overview of available API functions and how to retrieve activity data, we want to put that knowledge into practice. Assuming that only required users have access to your account, the focus should be on API keys to enhance account security. They are used both by users and service IDs. Moreover, API keys are generated for many purposes and could leak. Note that, by default, everyone in your account can create API keys. Our recommendation is to restrict it to those explicitly granted.

To check the authentication count and the timestamp of the last authentication for an API key, you’ll need the key’s ID and the right privilege. The key IDs can be obtained by getting all API keys, either all in the account or just for your own. Then, you’ll need to request the details, including the activity data and (optionally) the history. 

Instead of invoking the API functions individually and retrieving the results manually, we wrote a Python script: IAMkeys. It is available in the GitHub repository ibmcloud-iam-keys-identities. Typically, we try to obtain all JSON output and store it in a file, then use the tool jq for post-processing. See the README in the mentioned repository for sample commands and how to produce output in CSV (comma-separated values) format.

The following screenshot shows one of the retrieved API keys with history and activity data included. The API key was indirectly created by the account owner in April 2020 as part of a new Cloud Functions namespace. Because there is no authentication count and not a recorded timestamp for the last authentication, this API key should be investigated for deletion. If the Cloud Functions namespace no longer exists, the API key could be removed:

Metadata for an API key including history and activity details.

Report on inactive identities

Instead of generating your own report from the discussed APIs, you can use a recently introduced feature to identify inactive identities and simply create a report in the IBM Cloud console. It includes information about the users, service IDs, trusted profiles and API keys in the account. Each category is presented in its own browser tab. See the first screenshot at the top for parts of a report on API keys. For each listed identity, you have the option to manage or to remove it, but API keys can only be removed. The timestamp of when the report was generated is shown on top of the tabs. You can update the report by pressing the button:

Inactive identities report date and option to update the report.

Note that in the console, the report generation is always for 30 days (720 hours). Currently, you cannot modify the duration from there. In addition, only the latest available report is shown. The APIs to generate and retrieve the report offer more options as discussed earlier.

You can find a second Python script, IAMia, in the referenced GitHub repository. That script allows you to easily exercise the reporting functions. Moreover, it allows you to combine the new Activity Operations functions with the API functions from the previous section. As a result, it provides a more complete picture. Similar to the other script, it allows for output in either JSON or CSV format. See the repository for instructions.

Using the (CSV) data generated by the scripts, you can import the information into a spreadsheet or other data exploration tooling. Then, you can do the following:

  1. Filter using the last_authn column and identify all API keys, users or trusted profiles that have never authenticated.
  2. Identify a user with multiple API keys in your account; some of them are used and others are not. 
  3. Identify users, trusted profiles or service IDs that have a high authentication count and investigate if that should be of concern. 

Data generated from the script and imported into a spreadsheet for security analysis.


Having a good overview of all the service IDs and API keys in your IBM Cloud account adds to your security posture. In this blog post, we showed how the API functions of the IAM Identity Services can be utilized to generate insights on users, service IDs, trusted profiles and API keys in your account. They provide details about authentication activity and let you investigate if they are still active or could be removed for enhanced security.

We also discussed two Python scripts based on these API functions. The scripts allow you to produce the security-related data. The results can be post-processed with tools like jq (JSON format) or loaded into spreadsheets or databases (CSV format) for a deeper analysis. Check out the repository on GitHub for details on the scripts and to get started.

If you have feedback, suggestions, or questions about this post, please reach out to Henrik on Twitter (@data_henrik) or Dimitri and Henrik on LinkedIn. 


More from Cloud

Kubernetes version 1.28 now available in IBM Cloud Kubernetes Service

2 min read - We are excited to announce the availability of Kubernetes version 1.28 for your clusters that are running in IBM Cloud Kubernetes Service. This is our 23rd release of Kubernetes. With our Kubernetes service, you can easily upgrade your clusters without the need for deep Kubernetes knowledge. When you deploy new clusters, the default Kubernetes version remains 1.27 (soon to be 1.28); you can also choose to immediately deploy version 1.28. Learn more about deploying clusters here. Kubernetes version 1.28 In…

Temenos brings innovative payments capabilities to IBM Cloud to help banks transform

3 min read - The payments ecosystem is at an inflection point for transformation, and we believe now is the time for change. As banks look to modernize their payments journeys, Temenos Payments Hub has become the first dedicated payments solution to deliver innovative payments capabilities on the IBM Cloud for Financial Services®—an industry-specific platform designed to accelerate financial institutions' digital transformations with security at the forefront. This is the latest initiative in our long history together helping clients transform. With the Temenos Payments…

Foundational models at the edge

7 min read - Foundational models (FMs) are marking the beginning of a new era in machine learning (ML) and artificial intelligence (AI), which is leading to faster development of AI that can be adapted to a wide range of downstream tasks and fine-tuned for an array of applications.  With the increasing importance of processing data where work is being performed, serving AI models at the enterprise edge enables near-real-time predictions, while abiding by data sovereignty and privacy requirements. By combining the IBM watsonx data…

The next wave of payments modernization: Minimizing complexity to elevate customer experience

3 min read - The payments ecosystem is at an inflection point for transformation, especially as we see the rise of disruptive digital entrants who are introducing new payment methods, such as cryptocurrency and central bank digital currencies (CDBC). With more choices for customers, capturing share of wallet is becoming more competitive for traditional banks. This is just one of many examples that show how the payments space has evolved. At the same time, we are increasingly seeing regulators more closely monitor the industry’s…