Managing service keys

In an IBM® Log Analysis instance you can create, delete, and view service keys by using the UI. You can also create and view 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.

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

You must use a logging 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 service keys for each 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 Log Analysis:

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 through the UI.

Creating a service key by using the logging UI

You must have the manager role for the Log Analysis service to complete this step.

For more information, see service roles.

Complete the following steps to create a service key:

Launch the Log Analysis web UI.
Click the Settings icon .
Select Organization.
Select API keys.

If you have the correct permissions, the available service keys are displayed in the Service Keys section.
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 Log Analysis service to complete this step.

For more information, see service roles.

Complete the following steps to delete a service key:

Launch the IBM Log Analysis web UI.
Click the Settings icon .
Select Organization.
Select API keys.

If you have the correct permissions, the available service keys are displayed in the Service Keys section.
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 Log Analysis service to complete this step.

For more information, see service roles.

Complete the following steps to view a service key:

Launch the IBM Log Analysis web UI.
Click the Settings icon .
Select Organization.
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 Log Analysis instance by using the IBM Log Analysis Web UI, complete the following steps:

Launch the IBM Log Analysis web UI.
Click the Settings icon > Organization.
Select API keys.

You can see the service keys that are enabled.
Select Generate Service Key.

A new key is added to the list.
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 logging service key by using the CLI

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

Creating a service key by using the CLI

Only a single service key can be created 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 service key, use the UI or use the [API]](#service_keys_api_create).

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

[Pre-requisite] Install the IBM Cloud CLI.
Log in to the region in the IBM Cloud where the logging instance is running. Run the following command: ibmcloud login
Set the resource group where the logging instance is running. Run the following command: ibmcloud target

By default, the default resource group is set.
Get the instance name. Run the following command: ibmcloud resource service-instances
```
ibmcloud resource service-instances
```
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 logging service key for the instance.
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 logging instance ID. Run the following command:
```
ibmcloud resource service-instance <LOGGING_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 logdna --service-instance <LOGGING_INSTANCE_ID]
```

Consider deleting the 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:

[Pre-requisite] Install the IBM Cloud CLI.
Log in to the region in the IBM Cloud where the logging instance is running. Run the following command: ibmcloud login
Set the resource group where the logging instance is running. Run the following command: ibmcloud target

By default, the default resource group is set.
Get the instance name. Run the following command: ibmcloud resource service-instances
```
ibmcloud resource service-instances
```
Get the name of the key that is associated with the logging 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.
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 logging 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 logging 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 logging 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 PUT  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 logging 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 logging 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:

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.
Create a new key. For more information, see Creating an service key.
Delete the old key. Make sure you use the ID of the key that you identified previously. For more information, see Deleting a key.
After you rotate the service key, you must update any operation processes where the service key is used with the new value.