IBM Cloud Docs
Managing service keys

Managing service keys

In an IBM Cloud Activity Tracker instance you can create, delete, and view auditing service keys by using the UI. You can also create and view auditing service keys by using the CLI and API.

As of 28 March 2024 the IBM Log Analysis and IBM Cloud Activity Tracker services are deprecated and will no longer be supported as of 30 March 2025. Customers will need to migrate to IBM Cloud Logs, which replaces these two services, prior to 30 March 2025. For information about IBM Cloud Logs, see the IBM Cloud Logs documentation.

A service key is a unique code that is passed in an API request to identify the calling application or user.

You must use an auditing service key to complete any of the following tasks:

  • Export data programmatically
  • Manage views and alerts programmatically by using the Configuration API or Terraform.
  • Configure resources such as groups, archiving, keys by using the Configuration API or Terraform.

You can enable a maximum of 20 auditing service keys for each auditing instance.

Prereqs. Check your IAM permissions to manage service keys

To generate a new service key or get an existing service key, you need the following roles on the IBM Cloud Activity Tracker:

  • Platform role operator, editor or administrator
  • Service role Manager

To restrict access to a service key, you need the following role on the IAM Identity Service service:

  • Platform role Administrator

Managing service keys by using the UI

You can create, delete, and view service keys by using the UI.

Creating a service key by using the UI

You must have the manager role for the IBM Cloud Activity Tracker service to complete this step.

For more information, see service roles.

Complete the following steps to create a service key:

  1. Launch the IBM Cloud Activity Tracker web UI.

  2. Select the Configuration icon Configuration icon.

  3. Select Organization.

  4. Select API keys.

    If you have the correct permissions, the available service keys are displayed in the Service Keys section.

  5. Click Generate Service Key. A new key is added to the list.

Deleting a service key by using the UI

You must have the manager role for the IBM Cloud Activity Tracker service to complete this step.

For more information, see service roles.

Complete the following steps to delete a service key:

  1. Launch the IBM Cloud Activity Tracker web UI.

  2. Select the Configuration icon Configuration icon.

  3. Select Organization.

  4. Select API keys.

    If you have the correct permissions, the available service keys are displayed in the Service Keys section.

  5. Delete the key by clicking the X next to the key to be deleted.

Viewing a service key by using the UI

You must have the manager role for the IBM Cloud Activity Tracker service to complete this step.

For more information, see service roles.

Complete the following steps to view a service key:

  1. Launch the IBM Cloud Activity Tracker web UI.

  2. Select the Configuration icon Configuration icon.

  3. Select Organization.

  4. Select API keys.

    If you have the correct permissions, the available service keys are displayed in the Service Keys section.

Rotating an service key through the UI

If the service key is compromised or you have a policy to renew it after a number of days, you can generate a new key and delete the old one.

To renew the service key for an IBM Cloud Activity Tracker instance by using the IBM Cloud Activity Tracker Web UI, complete the following steps:

  1. Launch the IBM Cloud Activity Tracker web UI.

  2. Click the Settings icon Settings icon > Organization.

  3. Select API keys.

    You can see the service keys that are enabled.

  4. Select Generate Service Key.

    A new key is added to the list.

  5. Delete the old service key. Click X next to the service key to be deleted.

After you reset the service key, you must update any operation processes where the service key is used with the new value.

Managing a service key by using the CLI

You can create and view service keys by using the IBM Cloud CLI.

Creating a service key by using the CLI

Only a single auditing service key can be created by using the CLI. Using these commands to create a service key where one already exists will not create a new key. If you need to create more than one auditing service key, use the UI or use the [API]](#service_keys_api_create).

To create an auditing service key for a auditing instance through the command line, complete the following steps:

  1. [Pre-requisite] Install the IBM Cloud CLI.

  2. Log in to the region in the IBM Cloud where the auditing instance is running. Run the following command: ibmcloud login

  3. Set the resource group where the auditing instance is running. Run the following command: ibmcloud target

    By default, the default resource group is set.

  4. Get the instance name. Run the following command: ibmcloud resource service-instances

    ibmcloud resource service-instances

  5. Create the IBM Cloud resource service key. Run the ibmcloud resource service-key-create command:

    ibmcloud resource service-key-create <NAME> --instance-name <SERVICE_INSTANCE>

    Where NAME is the desired name of the service key and SERVICE_INSTANCE is the name of the service instance from the previous step.

    The output from this command includes the field service_key that contains the service key for the instance.

  6. Restrict access to the IBM Cloud resource service key so that only users that have the administrator and manager roles can see information associated with the service key.

    Identify the service ID associated with the service that you created in the previous step. Run the following command to list all the service IDs that are available in the resource group:

    ibmcloud iam service-ids

    The ID column indicates the SERVICE_ID that is associated with the service key that you created in the previous step.

    Identify the auditing instance ID. Run the following command:

    ibmcloud resource service-instance <AUDITING_INSTANCE_NAME>

    Then, create a policy to restrict access to the service key:

    ibmcloud iam service-policy-create <SERVICE_ID> --roles Administrator,Manager --service-name logdnaat --service-instance <AUDITING_INSTANCE_ID]

Consider deleting the IBM Cloud resource service key. There is a limit on the number of service IDs per account. For more information, see IBM Cloud IAM limits.

To delete a service key, run the following command:

ibmcloud resource service-key-delete <NAME>

Getting the service key by using the CLI

To get the service key through the command line, complete the following steps:

  1. [Pre-requisite] Install the IBM Cloud CLI.

  2. Log in to the region in the IBM Cloud where the auditing instance is running. Run the following command: ibmcloud login

  3. Set the resource group where the auditing instance is running. Run the following command: ibmcloud target

    By default, the default resource group is set.

  4. Get the instance name. Run the following command: ibmcloud resource service-instances

    ibmcloud resource service-instances

  5. Get the name of the key that is associated with the auditing instance. Run the ibmcloud resource service-keys command:

    ibmcloud resource service-keys --instance-name <INSTANCE_NAME>

    where INSTANCE_NAME is the name of the instance that you obtained in the previous step.

  6. Get the IBM Cloud resource service key. Run the ibmcloud resource service-key command:

    ibmcloud resource service-key <KEY_NAME>

    where KEY_NAME is the name of the key obtained in the previous step.

    The output from this command includes the field service_key that contains a service key for the instance. If no service key has been created for the instance, or, if you do not have manager access, no service key will be returned.

Managing a service key by using the API

You can manage service keys by using the Configuration API.

List all keys

To list all service keys that are available in an instance, you can run the following request:

curl  https://API_ENDPOINT/v1/config/keys?type="service"
  -H 'content-type: application/json' \
  -H 'servicekey: SERVICE_KEY'

Where:

API_ENDPOINT
Depending on your account settings, you can use public or private endpoints to manage categories programmatically. For information about endpoints per region, see API endpoints.
SERVICE_KEY
Service key value. A service key is a unique code that is passed in an API request to identify the calling application or user. The service key is specific to a auditing instance. For more information on how to generate a service key, see Managing service keys.

For example, to list all the service keys that are available in an instance in US South, you can run the following request:

curl  https://api.us-south.logging.cloud.ibm.com/v1/config/keys?type="service"  -H "content-type: application/json"  -H "servicekey: xxxxxxxxx"

Get details on a key

To get information on an service key, you can run:

curl -X GET  https://API_ENDPOINT/v1/config/keys/KEY_ID
  -H 'content-type: application/json' \
  -H 'servicekey: SERVICE_KEY'

Where:

API_ENDPOINT
Depending on your account settings, you can use public or private endpoints to manage categories programmatically. For information about endpoints per region, see API endpoints.
KEY_ID
ID value of the service key for which you want to get details.
SERVICE_KEY
Service key value. A service key is a unique code that is passed in an API request to identify the calling application or user. The service key is specific to a auditing instance. For more information on how to generate a service key, see Managing service keys.

For example, to get information on an service key that is available in an instance in US South, you can run the following request:

curl  https://api.us-south.logging.cloud.ibm.com/v1/config/keys/123456789  -H "content-type: application/json"  -H "servicekey: xxxxxxxxx"

Create a key

curl -X POST  https://API_ENDPOINT/v1/config/keys?type="service"
  -H 'content-type: application/json' \
  -H 'servicekey: SERVICE_KEY' \
  -d '{"name": "KEY_NAME"}'

Where:

API_ENDPOINT
Depending on your account settings, you can use public or private endpoints to manage categories programmatically. For information about endpoints per region, see API endpoints.
SERVICE_KEY
Service key value. A service key is a unique code that is passed in an API request to identify the calling application or user. The service key is specific to a auditing instance. For more information on how to generate a service key, see Managing service keys.
KEY_NAME
Name that you want to give the key. The maximum size of a name is 30 characters.

Change the name of a key

curl -X POST  "https://API_ENDPOINT/v1/config/keys/KEY_ID"
  -H 'content-type: application/json' \
  -H 'servicekey: SERVICE_KEY' \
  -d '{"name": "KEY_NAME"}'

Where:

API_ENDPOINT
Depending on your account settings, you can use public or private endpoints to manage categories programmatically. For information about endpoints per region, see API endpoints.
SERVICE_KEY
Service key value. A service key is a unique code that is passed in an API request to identify the calling application or user. The service key is specific to a auditing instance. For more information on how to generate a service key, see Managing service keys.
KEY_ID
ID value of the service key for which you want to get details.
KEY_NAME
Name that you want to give the key. The maximum size of a name is 30 characters.

Delete a key

To delete an service key, run the following command.

curl -X DELETE "https://API_ENDPOINT/v1/config/keys/KEY_ID"
  -H 'content-type: application/json' \
  -H 'servicekey: SERVICE_KEY'

Where:

API_ENDPOINT
Depending on your account settings, you can use public or private endpoints to manage categories programmatically. For information about endpoints per region, see API endpoints.
KEY_ID
ID value of the service key to be deleted.
SERVICE_KEY
Service key value. A service key is a unique code that is passed in an API request to identify the calling application or user. The service key is specific to a auditing instance. For more information on how to generate a service key, see Managing service keys.

Rotating the service key by using the API

If the service key is compromised or you have a policy that requies renewal of a key after a number of days, you can generate a new key and delete the old one.

To rotate a key, complete the following steps:

  1. Get the details of the key that you want to rotate.

    You can list all service keys to obtain the ID of the key that you want to rotate. For more information, see Listing all service keys.

    If you know the Key ID, skip to the next step.

  2. Create a new key. For more information, see Creating an service key.

  3. Delete the old key. Make sure you use the ID of the key that you identified previously. For more information, see Deleting a key.

  4. After you rotate the service key, you must update any operation processes where the service key is used with the new value.