Managing user API keys

Managing user API keys

To manage the IBM Cloud API keys that are associated with your user identity or the ones that you have access to manage for other users in the account, go to Manage > Access (IAM) > API keys in the IBM Cloud console. On the API keys page, you can create, edit, or delete IBM Cloud API keys for yourself, and you can manage all classic infrastructure API keys for users that you are an ancestor of in the user hierarchy. In addition, if you are the account owner or a user assigned the required access to manage other user's API keys in the account, you can use the View filter to list and manage those API keys too.

Creating an API key

As an IBM Cloud user you might want to use an API key when you enable a program or script without distributing your password to the script. A benefit of using an API key can be that a user or organization can create several API keys for different programs and the API keys can be deleted independently if compromised without interfering with other API keys or even the user. You can create up to 20 API keys.

To create an API key for your user identity in the UI, complete the following steps:

1. In the IBM Cloud console, go to Manage > Access (IAM) > API keys.
2. Click Create an IBM Cloud API key.
3. Enter a name and description for your API key.
4. Click Create.
5. Then, click Show to display the API key. Or, click Copy to copy and save it for later, or click Download.

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 by using the CLI

To create an API key by using the CLI, use the following command:

1. Enter ibmcloud iam api-key-create NAME [-d DESCRIPTION] [-f, --file FILE] in your command prompt, and specify a name, description, and file for saving your key. See the following example:

ibmcloud iam api-key-create MyKey -d "this is my API key" --file key_file

Creating an API key by using the API

To create an 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": "My-apikey",
  "description": "my personal 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

If you want to change the name or the description of an API key, complete the following steps in the UI or CLI.

To edit an API key, complete the following steps:

1. In the IBM Cloud console, go to Manage > Access (IAM) > API keys.
2. Identify the row of the API key that you want to update, and click the Actions icon > Edit.
3. Update the information for your API key.
4. Click Apply.

To edit an API key that is not your own, but you have access to manage, go to the API keys page. Then, select the All user IBM Cloud API keys option from the View menu to find the API key.

Updating an API key using the CLI

To edit an API key by using the CLI, enter the following command:

1. Enter ibmcloud iam api-key-update NAME [-n NAME] [-d DESCRIPTION] in your command prompt, specifying the old name, new name, and new description for the key. For example,:

ibmcloud iam api-key-update MyCurrentName -n MyNewName -d "the new description of my key"

Updating an API key by using the API

To edit an API key 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": "My-apikey",
  "description": "my personal 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 an API key

For platform API keys that represent your user identity you can prevent the API key from being deleted by locking it. A locked API key is indicated by the Locked icon .

ibmcloud iam api-key-lock (NAME|UUID) [-f, --force]

ibmcloud iam api-key-lock test-api-key

ibmcloud iam api-key-unlock (NAME|UUID) [-f, --force]

ibmcloud iam api-key-unlock test-api-key

Locking and unlocking an API key by using the API

For platform API keys that represent your user identity 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);
  });

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

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/apikeys/APIKEY_UNIQUE_ID/lock' -H 'Authorization: Bearer TOKEN' -H 'Content-Type: application/json'

UnlockApiKeyOptions unlockApiKeyOptions = new UnlockApiKeyOptions.Builder()
    .id(apikeyId)
    .build();

service.unlockApiKey(unlockApiKeyOptions).execute();

const params = {
  id: apikeyId,
};

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

response = iam_identity_service.unlock_api_key(id=apikey_id)

print(response)

unlockAPIKeyOptions := iamIdentityService.NewUnlockAPIKeyOptions(apikeyID)

response, err := iamIdentityService.UnlockAPIKey(unlockAPIKeyOptions)
if err != nil {
  panic(err)
}

Deleting an API key

If you are using a key rotation strategy, you might want to delete an older key and replace it with a new key.

To delete an API key, complete the following steps:

1. In the IBM Cloud console, go to Manage > Access (IAM) > API keys.
2. Identify the row of the API key that you want to delete, and select Delete from the Actions menu.
3. Confirm the deletion by clicking Delete.

To delete an API key that is not your own, but you have access to manage, go to the API keys page. Then, select the All user IBM Cloud API keys option from the View menu to find the API key.

Deleting an API key by using the CLI

To delete an API key by using the CLI:

Enter ibmcloud iam api-key-delete NAME in your command prompt, specifying the name of the key to delete.

Deleting an API key by using the API

To delete an API key by 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 user 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 by using Terraform

Use the following steps to create access groups by using Terraform.

1. Create an argument in your main.tf file. The following example creates an access group by using the ibm_iam_api_key resource, where name is a unique name to identify the API key.

   resource "ibm_iam_api_key" "iam_api_key" {
    name        = "test1234"
   }
   

   The description property is only available if a description is provided during API key creation. 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 by using Terraform

Use the following steps to update an API key by using terraform:

1. In your Terraform configuration main.tf file, find the Terraform code that you used to create the iam_api_key.

2. The following example updates and API key by using the ibm_iam_api_key resource, where name is a unique name to identify the API key.

   resource "ibm_iam_api_key" "iam_api_key" {
    name        = "test1234"
    description = "API key for users"
   }
   

   The description property is only available if a description is provided during API key creation. For more information, see the argument reference details on the Terraform Identity and Access Management (IAM) page.

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
      

For more information, see the Terraform documentation.

Locking and unlocking an API key by using the API

For platform API keys that represent your user identity you can prevent the API key from being deleted by locking it.