Device Group Create REST Service

Use Device Group Create REST Service to create a device group, such as myLTO. The new device group is a child of a parent device family, such as LTO.

Operation
POST
URL
https://<host>:<port>/SKLM/rest/v1/deviceGroups/{groupName}

By default, Guardium® Key Lifecycle Manager server listens to the secure port 9443 (HTTPS) for communication. During IBM® Security Guardium Key Lifecycle Manager installation, you can modify this default port.

Request

Request Parameters
Parameter Description
host Specify the IP address or hostname of the IBM Security Guardium Key Lifecycle Manager server.
port Specify the port number on which the IBM Security Guardium Key Lifecycle Manager server listens for requests.
Request Headers
Header name Value
Content-Type application/json
Accept application/json
Authorization SKLMAuth userAuthId=<authIdValue>
Accept-Language Any valid locale that is supported by IBM Security Guardium Key Lifecycle Manager. For example, en or de.
Path parameters
Parameter name Description
groupName Specify a user-defined name for a device group. For example, myDivisionLTO Follow these rules to define a name:
  • Do not specify a reserved value of 3592, DS8K, DS8000, LTO, DS5000, GPFS, PEER_TO_PEER or GENERIC.
  • Do not specify a reserved value of TLSSERVER or TLSCLIENT.
  • The name must start with an alphabetic character, not a numeral. It can contain only alphanumeric characters and underscores.
  • The name cannot consist of a single underscore and must not exceed a length of 16 characters.
Request body

JSON object with the following specification:

JSON property name Description
deviceFamily Specify an existing device family that IBM Security Guardium Key Lifecycle Manager provides. You can specify the following device family:
LTO
Specifies the LTO device family.
3592
Specifies the 3592 device family.
DS5000
Specifies the DS5000 device family.
GPFS
Specifies the IBM Spectrum® Scale (previously known as GPFS) device group.
PEER_TO_PEER
Specifies the PEER_TO_PEER device group.
GENERIC
Specifies a device family that uses KMIP to interact with IBM Security Guardium Key Lifecycle Manager. The GENERIC device group enables management of KMIP objects.
device.enableMachineAffinity Specify the device groups in the DS5000 device family that enabled to store the association of a device to an existing system identifier in the IBM Security Guardium Key Lifecycle Manager database. The values are true (enable) or false (disable). An instance of the property is stored for each device group.
enableKMIPDelete Enables or disables KMIP delete requests. Disabling this attribute when you create a device group prevents KMIP clients from deleting keys in the device group. Default is false (disabled).
shortName Specify a short label that is usually a drive type such as LTO. This property is used for any additional attributes that are needed by an original equipment manufacturer.
longName Specify an extended descriptive name of a drive type, such as my division LTO. For example, it might include business information.

Response

Response Headers
Header name Value and description
Status Code
200 OK
The request was successful. The response body contains the requested representation.
400 Bad Request
The authentication information was not provided in the correct format.
401 Unauthorized
The authentication credentials were missing or incorrect.
404 Not Found Error
The processing of the request fails.
500 Internal Server Error
The processing of the request fails because of an unexpected condition on the server.
Content-Type application/json
Content-Language Locale for the response message.
Success response body

JSON object with the following specification:

JSON property name Description
DeviceGroupName Returns the name of the group that is created.
Error Response Body

JSON object with the following specification.

JSON property name Description
code Returns the application error code.
message Returns a message that describes the error.

Examples

Service request to create a device group
POST https://localhost:<port>/SKLM/rest/v1/deviceGroups/newGroup
Content-Type: application/json
Accept: application/json
Authorization: SKLMAuth userAuthId=139aeh34567m
{"deviceFamily":"LTO","shortName":"myLTO","longName":"my companyname LTO 
devices"}
Success response
Status Code: 200 OK
{"code":"0","status":"Succeeded"}
Error response
Status Code: 400 Bad Request
{"code":"CTGKM6002E","message":"CTGKM6002E Bad Request: Invalid user 
authentication ID or invalid request format."}