Working with ingestion keys

The ingestion key is a security key that you must use to configure logging agents and successfully forward logs to your IBM Log Analysis instance in IBM Cloud. You automatically get the ingestion key when you provision an instance.

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.

To work with ingestion keys through the IBM Log Analysis Web UI, you must have an IAM policy with platform role Viewer and service role Manager for the IBM Log Analysis service.

Getting ingestion keys

Getting the ingestion key through the IBM Cloud UI

To get the ingestion key for an IBM Log Analysis instance by using the IBM Cloud UI, complete the following steps:

Log in to your IBM Cloud account.
Go to the Menu icon > Observability.
Click Logging. The IBM Log Analysis dashboard opens. You can see the list of logging instances that are available on IBM Cloud.
Identify the instance that you want to use to collect your cluster logs.
Click the Actions icon > View key.

A window opens where you can click Show to view the ingestion key.

Getting the key through the Log Analysis web UI

To get the ingestion 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 > API keys.

You can see the ingestion keys that are enabled.
Copy the ingestion key that shows in the API keys section.

Creating a service key by using the logging 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 create 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 Ingestion keys section.
Click Generate Ingestion 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 an ingestion 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 Ingestion Keys section.
Delete the key by clicking the X next to the key to be deleted.

Rotating an ingestion key through the UI

If the ingestion 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 ingestion 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 ingestion keys that are enabled.
Select Generate Ingestion Key.

A new key is added to the list.
Delete the old ingestion key. Click X next to the ingestion key to be deleted.

After you reset the ingestion key, you must update the ingestion key for any log sources that you have configured to forward logs to this IBM Log Analysis instance.

For example, see Resetting the ingestion key that is used by a Kubernetes cluster.

Getting the ingestion key through the CLI

To get the ingestion 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
```
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 ingestion key. Run the ibmcloud resource service-key command:
```
ibmcloud resource service-key APIKEY_NAME
```
where APIKEY_NAME is the name of the API key.

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

Managing ingestion keys through the API

You can use the configuration API to manage keys.

List all keys

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

curl  https://API_ENDPOINT/v1/config/keys?type="ingestion"
  -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 ingestion 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="ingestion"  -H "content-type: application/json"  -H "servicekey: xxxxxxxxx"

Get details on a key

To get information on an ingestion 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 ingestion 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 ingestion 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="ingestion"
  -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 ingestion 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 ingestion 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 ingestion 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 ingestion key by using the API

If the ingestion 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 ingestion keys to obtain the ID of the key that you want to rotate. For more information, see Listing all ingestion keys.

If you know the Key ID, skip to the next step.
Create a new key. For more information, see Creating an ingestion 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 ingestion key, you must update the ingestion key for any log sources that you have configured to forward logs to this Log Analysis instance. For example, see Resetting the ingestion key that is used by a Kubernetes cluster.