Managing service ID API keys

Creating an API key for a service ID

Create an API key to associate with a service ID in the console:

1. In the IBM Cloud console, go to Manage > Access (IAM), and select Service IDs.
2. If you don't have a service ID created, create the service ID.
3. Click the Actions icon > Manage service ID.
4. Click API keys.
5. Click Create.
6. Add a name and description to easily identify the API key.
7. Click Create.
8. Save your API key by copying or downloading it to secure location.

For security reasons, the API key is only available to be copied or downloaded at the time of creation. If the API key is lost, you must create a new API key.

Creating an API key for a service ID by using the CLI

To create an API key for a service ID by using the CLI, you can use the ibmcloud iam service-api-key-create command.

ibmcloud iam service-api-key-create NAME (SERVICE_ID_NAME|SERVICE_ID_UUID) [-d, --description DESCRIPTION] [--file FILE] [-f, --force] [--lock]

Updating an API key for a service ID by using the console

You can update an API key by editing the name or description that is used to identify the key in the UI.

1. In the IBM Cloud console, click Manage > Access (IAM), and select Service IDs.
2. Click the Actions icon > Manage service ID.
3. Click API keys.
4. Click the Actions icon > Edit name & description.

If you didn't create the service ID, but you are the account owner or an administrator for the IAM Identity service, you can update API keys for any service ID in the account. Go to the API keys page, and select the All service ID API keys option in the View menu to find the API key that you want to work with.

Updating an API key for a service ID by using the CLI

To update an API key for a service ID by using the CLI, you can use the ibmcloud iam service-api-key-update command.

ibmcloud iam service-api-key-update NAME SERVICE_ID [-n, --name NEW_sNAME] [-d, --description DESCRIPTION] [-v, --version VERSION] [-f, --force]

Locking a service ID's API key

For API keys that represent the identity of the service ID, you can prevent the API key from being deleted by locking it. A locked API key is indicated by the Locked icon in the UI.

1. In the IBM Cloud console, go to Manage > Access (IAM), and select Service IDs.
2. Identify the row of the service ID that you want to select an API key for, and select the name of the service ID.
3. Click API keys.
4. Hover on the row of the API key that you want to lock, and click the Actions icon to open a list of options.
5. Click Lock API key.

You can unlock your API key at any time to update, delete, or add an access policy, or to remove the API key.

Locking or unlocking a service ID API key with the CLI

For API keys that represent the identity of the service ID, you can prevent the API key from being deleted by locking it. A locked API key is indicated by the Locked icon in the UI. To lock a service ID API key, use the following command:

ibmcloud iam service-api-key-lock (APIKEY_NAME|APIKEY_UUID) (SERVICE_ID_NAME|SERVICE_ID_UUID) [-f, --force]

Prerequisites: Endpoint, Login, Target

Command options:

APIKEY_NAME

The name of the API key, exclusive with the APIKEY_UUID option. Required.

APIKEY_UUID

The UUID of the API key, exclusive with the APIKEY_NAME option. Required.

SERVICE_ID_NAME

The name of the service ID, exclusive with the SERVICE_ID_UUID option. Required.

SERVICE_ID_UUID

The UUID of the service, exclusive with the SERVICE_ID_NAME option. Required.

-f, --force

Lock without confirmation.

Examples:

Lock the service API key sample-key of service ID sample-service:

ibmcloud iam service-api-key-lock sample-key sample-service

To unlock a service ID API key, use the following command:

ibmcloud iam service-api-key-unlock (APIKEY_NAME|APIKEY_UUID) (SERVICE_ID_NAME|SERVICE_ID_UUID) [-f, --force]

Deleting an API key for a service ID

You can delete an API key that is associated with a service ID. However, deleting an API key that is used by an application removes the ability for that application to authenticate with your services.

1. In the console, go to Manage > Access (IAM), and select Service IDs.
2. If you don't have a service ID created, create the service ID.
3. Click the Actions icon > Manage service ID.
4. Click API keys.
5. Click the Actions icon > Delete.

If you didn't create the service ID, but you are the account owner or an administrator for the IAM Identity service, you can delete API keys for any service ID in the account. Go to the API keys page, and select the All service ID API keys option in the View menu to find the API key that you want to work with.

Deleting an API key for a service ID using the CLI

You can delete an API key that is associated with a service ID. However, deleting an API key that is used by an application removes the ability for that application to authenticate with your services. To delete an API key for a service ID by using the CLI, you can use the ibmcloud iam service-api-key-delete command.

ibmcloud iam service-api-key-delete NAME SERVICE_ID [-f, --force]

Creating an API key for a service ID using the API

To create a service ID API key, call the IAM Identity Service API as shown in the following example.

curl -X POST 'https://iam.cloud.ibm.com/v1/apikeys' -H 'Authorization: Bearer TOKEN' -H 'Content-Type: application/json' -d '{
  "name": "Service-apikey",
  "description": "my service key",
  "iam_id": "IBMid-123WEREW",
  "account_id": "ACCOUNT_ID"
  "store_value": false
}'

CreateApiKeyOptions createApiKeyOptions = new CreateApiKeyOptions.Builder()
    .name(apiKeyName)
    .iamId(iamId)
    .description("Example ApiKey")
    .build();

Response<ApiKey> response = service.createApiKey(createApiKeyOptions).execute();
ApiKey apiKey = response.getResult();
apikeyId = apiKey.getId();
System.out.println(apiKey.toString());

const params = {
  name: apikeyName,
  iamId: iamId,
  description: 'Example ApiKey',
};

iamIdentityService.createApiKey(params)
  .then(res => {
    apikeyId = res.result.id
    console.log(JSON.stringify(res.result, null, 2));
  })
  .catch(err => {
    console.warn(err);
  });

api_key = iam_identity_service.create_api_key(
  name=apikey_name,
  iam_id=iam_id
).get_result()

apikey_id = api_key['id']

print(json.dumps(api_key, indent=2))

createAPIKeyOptions := iamIdentityService.NewCreateAPIKeyOptions(apikeyName, iamID)
createAPIKeyOptions.SetDescription("Example ApiKey")

apiKey, response, err := iamIdentityService.CreateAPIKey(createAPIKeyOptions)
if err != nil {
  panic(err)
}
b, _ := json.MarshalIndent(apiKey, "", "  ")
fmt.Println(string(b))
apikeyID = *apiKey.ID

Updating an API key for a service ID using the API

To edit an API key for a service ID by using the API, call the IAM Identity Service API as shown in the following example:

curl -X PUT 'https://iam.cloud.ibm.com/v1/apikeys/APIKEY_UNIQUE_ID' -H 'Authorization: Bearer TOKEN' -H 'If-Match: <value of etag header from GET request>' -H 'Content-Type: application/json' -d '{
  "name": "Service-apikey",
  "description": "my service key"
}'

UpdateApiKeyOptions updateApiKeyOptions = new UpdateApiKeyOptions.Builder()
    .id(apikeyId)
    .ifMatch(apikeyEtag)
    .description("This is an updated description")
    .build();

Response<ApiKey> response = service.updateApiKey(updateApiKeyOptions).execute();
ApiKey apiKey = response.getResult();
System.out.println(apiKey.toString());

const params = {
  id: apikeyId,
  ifMatch: apikeyEtag,
  description: 'This is an updated description',
};

iamIdentityService.updateApiKey(params)
  .then(res => {
    console.log(JSON.stringify(res.result, null, 2));
  })
  .catch(err => {
    console.warn(err);
  });

api_key = iam_identity_service.update_api_key(
  id=apikey_id,
  if_match=apikey_etag,
  description='This is an updated description'
).get_result()

print(json.dumps(api_key, indent=2))

updateAPIKeyOptions := iamIdentityService.NewUpdateAPIKeyOptions(apikeyID, apikeyEtag)
updateAPIKeyOptions.SetDescription("This is an updated description")

apiKey, response, err := iamIdentityService.UpdateAPIKey(updateAPIKeyOptions)
if err != nil {
  panic(err)
}
b, _ := json.MarshalIndent(apiKey, "", "  ")
fmt.Println(string(b))

Locking and unlocking an API key for a service ID by using the API

For API keys that represent the identity of the service ID, you can prevent the API key from being deleted by locking it.

curl -X POST 'https://iam.cloud.ibm.com/v1/apikeys/APIKEY_UNIQUE_ID/lock' -H 'Authorization: Bearer TOKEN' -H 'Content-Type: application/json'

LockApiKeyOptions lockApiKeyOptions = new LockApiKeyOptions.Builder()
    .id(apikeyId)
    .build();

service.lockApiKey(lockApiKeyOptions).execute();

const params = {
  id: apikeyId,
};

iamIdentityService.lockApiKey(params)
  .then(res => {
    console.log(JSON.stringify(res.result, null, 2));
  })
  .catch(err => {
    console.warn(err);
  });

response = iam_identity_service.lock_api_key(id=apikey_id)

print(response)

lockAPIKeyOptions := iamIdentityService.NewLockAPIKeyOptions(apikeyID)

response, err := iamIdentityService.LockAPIKey(lockAPIKeyOptions)
if err != nil {
  panic(err)
}

curl -X DELETE 'https://iam.cloud.ibm.com/v1/serviceids/SERVICE_ID_UNIQUE_ID/lock' -H 'Authorization: Bearer TOKEN' -H 'Content-Type: application/json'

UnlockServiceIdOptions unlockServiceIdOptions = new UnlockServiceIdOptions.Builder()
    .id(svcId)
    .build();

service.unlockServiceId(unlockServiceIdOptions).execute();

const params = {
  id: svcId,
};

iamIdentityService.unlockServiceId(params)
  .then(res => {
    console.log(JSON.stringify(res.result, null, 2));
  })
  .catch(err => {
    console.warn(err);
    done(err);
  });

response = iam_identity_service.unlock_service_id(id=svc_id)

print(response)

unlockServiceIDOptions := iamIdentityService.NewUnlockServiceIDOptions(svcID)

response, err := iamIdentityService.UnlockServiceID(unlockServiceIDOptions)
if err != nil {
  panic(err)
}

Deleting an API key for a service ID using the API

To delete an API key by for a service ID using the API, call the IAM Identity Service API as shown in the following example:

curl -X DELETE 'https://iam.cloud.ibm.com/v1/apikeys/APIKEY_UNIQUE_ID' -H 'Authorization: Bearer TOKEN' -H 'Content-Type: application/json'

DeleteApiKeyOptions deleteApiKeyOptions = new DeleteApiKeyOptions.Builder()
    .id(apikeyId)
    .build();

service.deleteApiKey(deleteApiKeyOptions).execute();

const params = {
  id: apikeyId,
};

iamIdentityService.deleteApiKey(params)
  .then(res => {
    console.log(JSON.stringify(res.result, null, 2));
  })
  .catch(err => {
    console.warn(err);
  });

delete_api_key(self,
        id: str,
        **kwargs
    ) -> DetailedResponse

response = iam_identity_service.delete_api_key(id=apikey_id)

print(response)

deleteAPIKeyOptions := iamIdentityService.NewDeleteAPIKeyOptions(apikeyID)

response, err := iamIdentityService.DeleteAPIKey(deleteAPIKeyOptions)
if err != nil {
  panic(err)
}

Before you begin

Before you can manage service ID API keys by using Terraform, make sure that you have completed the following:

• Install the Terraform CLI and configure the IBM Cloud Provider plug-in for Terraform. For more information, see the tutorial for Getting started with Terraform on IBM Cloud®. The plug-in abstracts the IBM Cloud APIs that are used to complete this task.
• Create a Terraform configuration file that is named main.tf. In this file, you define resources by using HashiCorp Configuration Language. For more information, see the Terraform documentation.

Creating an API key for a service ID by using Terraform

Use the following steps to create an API key for a service ID by using Terraform.

1. Create an argument in your main.tf file. The following example creates an API key for a service ID by using the ibm_iam_service_api_key resource, where name is a unique name to identify the service API key. You must need an IAM ID of the service in order to complete the task.

   resource "ibm_iam_service_id" "serviceID" {
    name = "servicetest"
   }
   
   resource "ibm_iam_service_api_key" "testacc_apiKey" {
    name = "testapikey"
    iam_service_id = ibm_iam_service_id.serviceID.iam_id
   }
   

   For more information, see the argument reference details on the Terraform Identity and Access Management (IAM) page.

2. After you finish building your configuration file, initialize the Terraform CLI. For more information, see Initializing Working Directories.

   terraform init
   

3. Provision the resources from the main.tf file. For more information, see Provisioning Infrastructure with Terraform.

   1. Run terraform plan to generate a Terraform execution plan to preview the proposed actions.

      terraform plan
      

   2. Run terraform apply to create the resources that are defined in the plan.

      terraform apply
      

Updating an API key for a service ID by using Terraform

Use the following steps to update an API key for a service ID by using Terraform:

1. Create an argument in your main.tf file. You can update the API key for a service ID by adding new values to the name and iam_service_id options in the following example.

   resource "ibm_iam_service_id" "serviceID" {
    name = "servicetest"
   }
   
   resource "ibm_iam_service_api_key" "testacc_apiKey" {
    name = "testapikey"
    iam_service_id = ibm_iam_service_id.serviceID.iam_id
   }
   

   For more information, see the argument reference details on the Terraform Identity and Access Management (IAM) page.

2. After you finish building your configuration file, initialize the Terraform CLI. For more information, see Initializing Working Directories.

   terraform init
   

3. Provision the resources from the main.tf file. For more information, see Provisioning Infrastructure with Terraform.

   1. Run terraform plan to generate a Terraform execution plan to preview the proposed actions.

      terraform plan
      

   2. Run terraform apply to create the resources that are defined in the plan.

      terraform apply
      

Deleting an API key for a service ID by using Terraform

You must have created the API key for a service ID using the Terraform file. Use the following steps to delete an API key for a service ID by using Terraform.

1. The following example shows how to delete the API key for a service ID.

   resource "ibm_iam_service_id" "serviceID" {
    name = "servicetest"
   }
   
   resource "ibm_iam_service_api_key" "testacc_apiKey" {
    name = "testapikey"
    iam_service_id = ibm_iam_service_id.serviceID.iam_id
   }
   

   For more information, see the argument reference details on the Terraform Identity and Access Management (IAM) page.

2. After you finish building your configuration file, initialize the Terraform CLI. For more information, see Initializing Working Directories.

   terraform init
   

3. Provision the resources from the main.tf file. For more information, see Provisioning Infrastructure with Terraform.

   1. Run terraform plan to generate a Terraform execution plan to preview the proposed actions.

      terraform plan
      

   2. Run terraform apply to create the resources that are defined in the plan.

      terraform apply