Creating and working with service IDs

A service ID identifies a service or application similar to how a user ID identifies a user. You can create a service ID and use it to enable an application outside of IBM Cloud access to your IBM Cloud services. You can assign specific access policies to the service ID that restrict permissions for using specific services, or even combine permissions for accessing different services. Since service IDs are not tied to a specific user, if a user leaves an organization and is deleted from the account, the service ID remains. This way, your application or service stays up and running.

When you create a service ID, you create a unique name and description that is easy for you to identify and work with in the UI. After you create your service ID, you can create API keys specific to each service ID that your application can use to authenticate with your IBM Cloud services. To ensure that your application has the appropriate access for authenticating with your IBM Cloud services, you use access policies that are assigned to each service ID that you create.

The access policies that are associated with a service ID enable specific actions that can be taken when that service ID is used to access a specific service. A service ID can be assigned multiple policies for different Identity and access-enabled services, and even different instances of a single service. For example, you have two services with two service instances each. You might assign the Viewer role for all available instances of one service and assign the Editor role for only one instance of a second service. This way, you can customize access to multiple services, but use a single API key for authentication to all.

All users have access to create a service ID in an account to which they are a member. However, to allow a user in an account access to view or manage a service ID that they did not personally create, they must have access with a role on the IAM Identity account management service. For more information, see IAM Identity service.

You can assign any identity access to view or manage a service ID by using access management tags. For more information, see Attaching tags to a service ID.

If the Restrict service ID creation IAM account setting is enabled, then everyone in the account, including account owners, is blocked from creating service IDs unless they are assigned explicit access. For more information, see Restricting users from creating service IDs.

Creating a service ID by using the console

To create a service ID, complete the following steps:

In the IBM Cloud console, go to Manage > Access (IAM), and select Service IDs.
Click Create.
Follow the process to create a name and description for your service ID.
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

Command options

NAME (required): Name of the service.
-d, --description: Description of the service ID.
--lock: Lock the service ID during creation.

Examples

Create a service ID with service name sample-test and description hello, world!:

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

Create a locked service ID with service name sample-test and description 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:

In the IBM Cloud console, go to Manage > Access (IAM), and select Service IDs.
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]

Command options

--uuid: Show UUID of service IDs only.

Examples

List the UUID of all service IDs in the current account:

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:

In the IBM Cloud console, go to Manage > Access (IAM), and select Service IDs.
Identify the row of the service ID that you want to view the details of, and click it.
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]

Command options

NAME (required): The name of the service, exclusive with UUID.
UUID (required): The UUID of the service, exclusive with NAME.
--uuid: Displays the UUID of the service ID.

Examples

The following example shows the details of service ID sample-test:

ibmcloud iam service-id sample-test

The following example shows the details of service ID ServiceId-cb258cb9-8de3-4ac0-9aec-b2b2d27ac976:

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

Command options

NAME (required): Name of the service, exclusive with UUID.
UUID (required): UUID of the service, exclusive with NAME.
-n, --name: New name of the service.
d, --description: New description of the service.
-f, --force: Update without confirmation.

Examples

Rename service ID sample-test to sample-test-2 without confirmation:

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

Update description of service sample-test:

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

Rename service ID ServiceId-cb258cb9-8de3-4ac0-9aec-b2b2d27ac976 to sample-test-3 with new description:

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:

In the IBM Cloud console, go to Manage > Access (IAM), and select Service IDs.
Identify the row of the service ID that you want to remove, and click the Actions icon > Remove.
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.

Command options

NAME (required): Name of the service, exclusive with UUID.
UUID (required): UUID of the service, exclusive with NAME.
-f, --force: Delete without confirmation.

Either NAME or UUID are required, but you don't need to provide both.

Examples

Delete service ID sample-teset without confirmation:

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

Delete service ID ServiceId-cb258cb9-8de3-4ac0-9aec-b2b2d27ac976:

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

For more information about managing API keys by using the CLI, see Managing IAM access.

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.

Locking a service ID

To avoid a situation where your service ID is deleted causing an outage or disruption for the users of your service, you have the option to lock your service ID. Locking a service ID also prevents any policies from being changed, deleted, or assigned. In addition to the ability to lock a service ID, you can lock individual API keys that are associated with each service ID that you create in your account.

While locked service IDs cannot be deleted from the account and the access policies can't be updated, locked service IDs can still be removed from any access group that they are added to. This means that any access that is assigned to the ID by its membership in an access group is removed when the service ID is removed from the access group.

Providing user access for locking service IDs

In order for a user to have access to lock and unlock service IDs and API keys that are associated with service IDs, they must be assigned a specific access policy. Two types of access policies can grant the proper access: access to all service IDs in the account or access to a specific service ID in the account

To assign access to all service IDs in the account, set an access policy for account management services with the following details:

Editor or Administrator role
IAM Identity Service

To assign access to a specific service ID in the account, set an access policy for account management services with the following details:

Editor or Administrator role
IAM Identity Service
Specify serviceid in the Resource type field
Specify the service ID identifier in the Resource ID field

To get the identifier of a specific service ID, go to Manage > Access (IAM) in the IBM Cloud console, and select Service IDs. Select the service ID that you want to view details for, and copy the ID value.

Locking a service ID by using the console

A locked service ID is indicated by the Locked icon Locked icon .

In the IBM Cloud console, click Manage > Access (IAM) and then select Service IDs.
Identify the row of the service ID that you want to lock, and click the Actions icon > Lock.

Locking a service ID by using the CLI

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

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

Command options

NAME (required): Name of the service, exclusive with UUID.
UUID (required): UUID of the service, exclusive with NAME.
-f, --force: Lock without confirmation.

Examples

Lock service ID sample-test without confirmation:

ibmcloud iam service-id-lock sample-test -f

Lock service ID ServiceId-cb258cb9-8de3-4ac0-9aec-b2b2d27ac976:

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

Unlocking a service ID by using the console

To unlock a service ID, complete the following steps:

In the IBM Cloud console, click Manage > Access (IAM) and then select Service IDs.
Identify the row of the service ID that you want to unlock, and click the Actions icon > Unlock.

You must have the appropriate level of access to unlock a service ID.

Unlocking a service ID by using the CLI

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

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

Command options

NAME (required): Name of the service, exclusive with UUID.
UUID (required): UUID of the service, exclusive with NAME.
-f, --force: Unlock without confirmation.

Examples

Unlock service ID sample-test without confirmation:

ibmcloud iam service-id-unlock sample-test -f

Unlock service ID ServiceId-cb258cb9-8de3-4ac0-9aec-b2b2d27ac976:

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

Locking a service ID by using the API

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

LockServiceIdOptions lockServiceIdOptions = new LockServiceIdOptions.Builder()
    .id(svcId)
    .build();

service.lockServiceId(lockServiceIdOptions).execute();

const params = {
  id: svcId,
};

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

response = iam_identity_service.lock_service_id(id=svc_id)

print(response)

lockServiceIDOptions := iamIdentityService.NewLockServiceIDOptions(svcID)

response, err := iamIdentityService.LockServiceID(lockServiceIDOptions)
if err != nil {
  panic(err)
}

For more information, see the IAM Identity Services API.

Unlocking a service ID by using the API

To unlock 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/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)
}

For more information, see the IAM Identity Services API.

Examples of how to use a service ID

The following are examples of how a Service ID is used with the Object Storage and IBM Cloud Data Engine services.

Object Storage - Use the IBM Cloud CLI.
IBM Cloud Data Engine - How to use the IBM Cloud Data Engine REST API.