Ownership

Location /api/apps/{appID}/things/VENDOR_THING_ID:{vendorThingID}/ownership
Resource to manage the ownerships of the thing. A thing can have more than one ownership, each ownership can involve any user or group in the application. Adding a group as owner means all group members are owners of the thing.

Request Headers (Applies to all methods)

Authorization
header
Required: Yes

POST

/api/apps/{appID}/things/VENDOR_THING_ID:{vendorThingID}/ownership

Description

Add the user or group as the new thing owner in a secure way.

Security

The administrator can add any user as a thing owner. A user or group member can add himself as a thing owner.

Content-Type application/vnd.kii.ThingOwnershipRequest+json

Add the user or group as the new thing owner in a secure way. This operation behavior changes depending on 'requirePasswordForThingOwnership' app parameter in the way that if the app parameter value is 'false', the ownership will be added without any password, although a password is sent, the API will ignore it, whereas if app parameter is 'true' adding a new thing owner will be rejected if the password is not provided or the provided password is invalid.

Headers
Name Required? type Description
Authorization Yes string Authorization header. OAuth2 Bearer token
Authorization Yes string Authorization can be of type Basic or Bearer.
  • Authorization Basic: header for granting an anonymous access.
    • Set a Base64-encoded string of AppID and AppKey concatenated with a colon (APP_ID:APP_KEY).
    • The header should look like:
      Authorization: Basic czZCaGRSa3F0Mzo3RmpmcDBaQnIxS3REUmJuZlZkbUl3
  • Authorization Bearer: using Oauth2 Bearer Token.
    • The header should look like:
      Authorization: Bearer ht5fpHQAyrPPwLftK1rAqllv5WNVPCnYfPiCvPocFuQ
Params
Name Required? Type Description
userID string The userID to add as owner of the thing. (Mandatory if groupID is not sent)
groupID string The groupID to add as owner of the thing. (Mandatory if userID is not sent)
thingPassword string Password of the target thing.
Sample Request 
{
  "userID": "[string]",
  "groupID": "[string]",
  "thingPassword": "[string]"
}
Responses
204

Content-Type (None)

The user or group has been added as an owner.
Note This response has no contents.
404

Content-Type application/vnd.kii.UserNotFoundException+json

The user was not found.
Contents
Name Type Description
errorCode string Error code "USER_NOT_FOUND".
message string The error message.
field string The field used for searching the user. This can be the userID or address field.
value string The field value used for searching the user.
appID string The ID of the application.
404

Content-Type application/vnd.kii.GroupNotFoundException+json

The group was not found.
Contents
Name Type Description
errorCode string Error code "GROUP_NOT_FOUND".
message string The error message.
groupID string The groupID of the group.
appID string The ID of the application.
404

Content-Type application/vnd.kii.ThingNotFoundException+json

The thing was not found.
Contents
Name Type Description
errorCode string Error code "THING_NOT_FOUND".
message string The error message.
field string The field used for searching the thing. This can be the "thingID" or "vendorThingID" field.
value string The field value used for searching the thing.
appID string The ID of the application.
409

Content-Type application/vnd.kii.ThingOwnershipAlreadyExistsException+json

The user or group was already an owner.
Contents
Name Type Description
errorCode string Error code "THING_OWNERSHIP_ALREADY_EXISTS".
message string The error message.
appID string The ID of the application.
thingID string The ID of the thing.
userID string The ID of the user.
groupID string The ID of the group.
400

Content-Type application/vnd.kii.ValidationException+json

None of userID or groupID was provided.
Contents
Name Type Description
errorCode string Error code "INVALID_INPUT_DATA".
message string The error message.
400

Content-Type application/vnd.kii.ValidationException+json

Both userID and groupID were provided.
Contents
Name Type Description
errorCode string Error code "INVALID_INPUT_DATA".
message string The error message.
401

Content-Type application/vnd.kii.UnauthorizedAccessException+json

Not authorized to add the user or group as an owner.
Contents
Name Type Description
errorCode string Error code "UNAUTHORIZED".
message string The error message.
authenticatedAppID string The authenticated appID.
authenticatedPrincipalID string The authenticated principal ID (userID or thingID).
401

Content-Type application/vnd.kii.UnauthorizedAccessException+json

“requirePasswordForThingOwnership” is set to true and “thingPassword” is not provided, or does not match with the thing’s password.
Contents
Name Type Description
errorCode string Error code "UNAUTHORIZED".
message string The error message.
authenticatedAppID string The authenticated appID.
authenticatedPrincipalID string The authenticated principal ID (userID or thingID).

GET

/api/apps/{appID}/things/VENDOR_THING_ID:{vendorThingID}/ownership

description

Get a list of thing owners.

Security

The administrator and the thing itself can perform this operation.

Headers
Name Required? type Description
Authorization Yes string Authorization header. OAuth2 Bearer token
Responses
200

Content-Type application/vnd.kii.ThingOwnershipRetrievalResponse+json

A list of thing owners is successfully retrieved.
Contents
Name Type Description
users string Array of thing owner's userIDs. The array will be empty if there is no owner user.
groups string Array of thing owner's groupIDs. The array will be empty if there is no owner group.
404

Content-Type application/vnd.kii.ThingNotFoundException+json

The thing was not found.
Contents
Name Type Description
errorCode string Error code "THING_NOT_FOUND".
message string The error message.
field string The field used for searching the thing. This can be the "thingID" or "vendorThingID" field.
value string The field value used for searching the thing.
appID string The ID of the application.
401

Content-Type application/vnd.kii.UnauthorizedAccessException+json

Not authorized to retrieve the ownerships of the thing.
Contents
Name Type Description
errorCode string Error code "UNAUTHORIZED".
message string The error message.
authenticatedAppID string The authenticated appID.
authenticatedPrincipalID string The authenticated principal ID (userID or thingID).