Creating and working with service IDs

Creating a service ID by using the console

To create a service ID, complete the following steps:

1. In the IBM Cloud console, go to Manage > Access (IAM), and select Service IDs.
2. Click Create.
3. Follow the process to create a name and description for your service ID.
4. Click Create.

Then, hover on the row of a service ID to click the Actions icon to manage your service ID. You can start by assigning a policy and creating API keys. For more information about working with API keys, see Managing service ID API keys.

Creating a service ID by using the CLI

To create a service ID, use the ibmcloud iam service-id-create command:

ibmcloud iam service-id-create NAME [-d, --description DESCRIPTION] [--lock]

Prerequisite

Endpoint, Login, Target

ibmcloud iam service-id-create sample-test -d 'hello, world!'

ibmcloud iam service-id-create sample-test -d 'hello, world!' --lock

Creating a service ID by using the API

To create a service ID, call the IAM Identity Services API as shown in the following example:

curl -X POST 'https://iam.cloud.ibm.com/v1/serviceids' -H 'Authorization: Bearer TOKEN' -H 'Content-Type: application/json' -d '{
  "name": "My-serviceID",
  "description": "my special service ID",
  "account_id": "ACCOUNT_ID"
}'

CreateServiceIdOptions createServiceIdOptions = new CreateServiceIdOptions.Builder()
    .accountId(accountId)
    .name(serviceIdName)
    .description("Example ServiceId")
    .build();

Response<ServiceId> response = service.createServiceId(createServiceIdOptions).execute();
ServiceId serviceId = response.getResult();
svcId = serviceId.getId();
System.out.println(serviceId.toString());

const params = {
  accountId: accountId,
  name: serviceIdName,
  description: 'Example ServiceId',
};

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

service_id = iam_identity_service.create_service_id(
  account_id=account_id,
  name=serviceid_name,
  description='Example ServiceId'
).get_result()

svc_id = service_id['id']

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

createServiceIDOptions := iamIdentityService.NewCreateServiceIDOptions(accountID, serviceIDName)
createServiceIDOptions.SetDescription("Example ServiceId")

serviceID, response, err := iamIdentityService.CreateServiceID(createServiceIDOptions)
if err != nil {
  panic(err)
}
svcID = *serviceID.ID
b, _ := json.MarshalIndent(serviceID, "", "  ")
fmt.Println(string(b))

For more information, see the IAM Identity Services API.

Listing service IDs by using the console

List the service IDs in your account to review the applications that have access to your services by completing the following steps:

1. In the IBM Cloud console, go to Manage > Access (IAM), and select Service IDs.
2. Review the list of service IDs.

Listing service IDs by using the CLI

You can list and review all service IDs in your account by running the ibmcloud iam service-ids command:

ibmcloud iam service-ids [--uuid]

ibmcloud iam service-ids --uuid

Listing service IDs by using the API

You can programmatically list all service IDs in your account by calling the IAM Identity Services API as shown in the following sample requests:

curl -X GET "https://iam.cloud.ibm.com/v1/serviceids?account_id=ACCOUNT_ID" \
--header "Authorization: Bearer $TOKEN" \
--header "Content-Type: application/json" 

ListServiceIdsOptions listServiceIdsOptions = new ListServiceIdsOptions.Builder()
    .accountId(accountId)
    .build();

Response<ServiceIdList> response = service.listServiceIds(listServiceIdsOptions).execute();
ServiceIdList serviceIdList = response.getResult();

System.out.println(serviceIdList);

const params = {
  accountId: accountId,
};

try {
  const res = await iamIdentityService.listServiceIds(params)
  console.log(JSON.stringify(res.result, null, 2));
} catch (err) {
  console.warn(err);
}

service_id_list = iam_identity_service.list_service_ids(
  account_id=account_id,
).get_result()
print(json.dumps(service_id_list, indent=2))

listServiceIdsOptions := iamIdentityService.NewListServiceIdsOptions()
listServiceIdsOptions.SetAccountID(accountID)

serviceIDList, response, err := iamIdentityService.ListServiceIds(listServiceIdsOptions)
if err != nil {
  panic(err)
}
b, _ := json.MarshalIndent(serviceIDList, "", "  ")
fmt.Println(string(b))

For more information, see the IAM Identity Services API.

Viewing the details of a service ID by using the console

You can view the details of a service ID, including the access groups, assigned policies, and all associated API keys.

To view service ID details, complete the following steps:

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 view the details of, and click it.
3. Review the details of access groups, access policies, and API keys.

Viewing the details of a service ID by using the CLI

To view service ID details, use the ibmcloud iam service-id command:

ibmcloud iam service-id (NAME|UUID) [--uuid]

ibmcloud iam service-id sample-test

ibmcloud iam service-id ServiceId-cb258cb9-8de3-4ac0-9aec-b2b2d27ac976

Viewing the details of a service ID by using the API

You can programmatically view the details of a service ID in your account by calling the IAM Identity Services API as shown in the following sample requests:

curl -X GET "https://iam.cloud.ibm.com/v1/serviceids/SERVICE_ID_UNIQUE_ID" \
--header "Authorization: Bearer $TOKEN" \
--header "Content-Type: application/json" 

GetServiceIdOptions getServiceIdOptions = new GetServiceIdOptions.Builder()
    .id(svcId)
    .includeActivity(false)
    .build();

Response<ServiceId> response = service.getServiceId(getServiceIdOptions).execute();
ServiceId serviceId = response.getResult();
svcIdEtag = response.getHeaders().values("Etag").get(0);

System.out.println(serviceId);

const params = {
  id: svcId,
  includeActivity: true,
};

try {
  const res = await iamIdentityService.getServiceId(params)
  svcIdEtag = res.headers['etag'];
  console.log(JSON.stringify(res.result, null, 2));
} catch (err) {
  console.warn(err);
}

response = iam_identity_service.get_service_id(
  id=svc_id,
  include_history=True,
  include_activity=True,
)
service_id = response.get_result()
print(json.dumps(service_id, indent=2))

getServiceIDOptions := iamIdentityService.NewGetServiceIDOptions(svcID)

getServiceIDOptions.SetIncludeActivity(false)

serviceID, response, err := iamIdentityService.GetServiceID(getServiceIDOptions)
if err != nil {
  panic(err)
}
svcIDEtag = response.GetHeaders().Get("Etag")
b, _ := json.MarshalIndent(serviceID, "", "  ")
fmt.Println(string(b))

For more information, see the IAM Identity Services API.

Updating a service ID by using the console

You can update a service ID by changing the name and description at any time. You can also delete and create new API keys as needed or update the assigned access policies. Hover on the row of a service ID to click the Actions icon to manage your service ID.

Any changes that you make to an existing service ID, such as changing the assigned policies or deleting an API key that is used, might cause service interruptions to applications that use that service ID.

Updating a service ID by using the CLI

To update the service ID, use the ibmcloud iam service-id-update command:

ibmcloud iam service-id-update (NAME|UUID) [-n, --name NEW_NAME] [-d, --description DESCRIPTION] [-f, --force]

Prerequisites

Endpoint, Login, Target

ibmcloud iam service-id-update sample-test -n sample-test-2 -f

ibmcloud iam service-id-update sample-test -d 'hello, friend!'

ibmcloud iam service-id-update ServiceId-cb258cb9-8de3-4ac0-9aec-b2b2d27ac976 -n sample-test-3 -d 'hello, my friends!'

Updating a service ID by using the API

To update a service ID, call the IAM Identity Services API as shown in the following example:

curl -X PUT 'https://iam.cloud.ibm.com/v1/serviceids/SERVICE_ID_UNIQUE_ID' -H 'Authorization: Bearer TOKEN' -H 'If-Match: <value of etag header from GET request>' -H 'Content-Type: application/json' -d '{
  "name": "My-super-secret-serviceid",
  "description": "super secret service ID"
}'

UpdateServiceIdOptions updateServiceIdOptions = new UpdateServiceIdOptions.Builder()
    .id(svcId)
    .ifMatch(svcIdEtag)
    .description("This is an updated description")
    .build();

Response<ServiceId> response = service.updateServiceId(updateServiceIdOptions).execute();
ServiceId serviceId = response.getResult();
System.out.println(serviceId.toString());

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

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

service_id = iam_identity_service.update_service_id(
  id=svc_id,
  if_match=svc_id_etag,
  description='This is an updated description'
).get_result()

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

updateServiceIDOptions := iamIdentityService.NewUpdateServiceIDOptions(svcID, svcIDEtag)
updateServiceIDOptions.SetDescription("This is an updated description")

serviceID, response, err := iamIdentityService.UpdateServiceID(updateServiceIDOptions)
if err != nil {
  panic(err)
}
b, _ := json.MarshalIndent(serviceID, "", "  ")
fmt.Println(string(b))

For more information, see the IAM Identity Services API.

Deleting a service ID by using the console

To delete a service ID, complete the following steps:

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 remove, and click the Actions icon > Remove.
3. Click Remove.

Deleting a service ID also deletes all associated API keys and assigned policies. This action can't be undone, and might cause disruptions between dependent services.

Deleting a service ID by using the CLI

To delete a service ID, use the ibmcloud iam service-id-delete command:

ibmcloud iam service-id-delete (NAME|UUID) [-f, --force]

Deleting a service ID also deletes all associated API keys and assigned policies. This action can't be undone, and might cause disruptions between dependent services.

ibmcloud iam service-id-delete sample-teset -f

ibmcloud iam service-id-delete ServiceId-cb258cb9-8de3-4ac0-9aec-b2b2d27ac976

Deleting a service ID by using the API

To delete a service ID, call the IAM Identity Services API as shown in the following example:

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

DeleteServiceIdOptions deleteServiceIdOptions = new DeleteServiceIdOptions.Builder()
    .id(svcId)
    .build();

Response<Void> response = service.deleteServiceId(deleteServiceIdOptions).execute();

const params = {
  id: svcId,
};

iamIdentityService.deleteServiceId(params)
  .then(res => {
    done();
  })
  .catch(err => {
    console.warn(err);
  });

response = iam_identity_service.delete_service_id(id=svc_id)

deleteServiceIDOptions := iamIdentityService.NewDeleteServiceIDOptions(svcID)

response, err := iamIdentityService.DeleteServiceID(deleteServiceIDOptions)
if err != nil {
  panic(err)
}

Deleting a service ID also deletes all associated API keys and assigned policies. This action can't be undone, and might cause disruptions between dependent services.

For more information, see the IAM Identity Services API.