Ownership Management

Kii Cloud lets you manage the owners of things by offering the following features.

• Adding Owners
• Checking the Ownership
• Getting a list of Owners
• Removing the Ownership

Adding Owners

We supports two flows (password flow and PIN code validation flow) for adding a new thing owner.

Password flow

A user can add himself or a group to which he belongs as a thing owner by providing the thing's password.

This is an example of adding a user as a new owner.

curl -v -X POST \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "Content-Type: application/vnd.kii.ThingOwnershipRequest+json" \
  "https://api-jp.kii.com/api/apps/{APP_ID}/things/{THING_ID}/ownership" \
  -d '{
        "userID": "{USERID_OF_THE_OWNER}",
        "thingPassword": "{PASSOWORD_OF_THE_THING}"
      }'

The next example adds a group as a new owner.

curl -v -X POST \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "Content-Type: application/vnd.kii.ThingOwnershipRequest+json" \
  "https://api-jp.kii.com/api/apps/{APP_ID}/things/{THING_ID}/ownership" \
  -d '{
        "groupID": "{GROUPID_OF_THE_OWNER_GROUP}",
        "thingPassword": "{PASSOWORD_OF_THE_THING}"
      }'

If successful, Kii Cloud returns a 204 response.

PIN code validation flow

This flow introduces a PIN validation in the process. Kii Cloud will create a PIN code for adding a new thing owner. Sending this PIN code is required when adding a new thing owner. See PIN Code Validation Flow for the overview.

Requesting a PIN Code:

This is an example of requesting a PIN code for adding a user as a new owner.

curl -v -X POST \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  "https://api-jp.kii.com/api/apps/{APP_ID}/things/{THING_ID}/ownership/request/user:{USER_ID}"

The next example is requesting a PIN code for adding a group as a new owner.

curl -v -X POST \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  "https://api-jp.kii.com/api/apps/{APP_ID}/things/{THING_ID}/ownership/request/group:{GROUP_ID}"

In both cases, the PIN code is returned as follows:

200 OK
{
  "code" : "XXXXXXXXXXX"
}

Validating the PIN Code:

This is an example of how you validate the PIN code.

curl -v -X POST \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "Content-Type: application/vnd.kii.ThingOwnershipConfirmationRequest+json" \
  "https://api-jp.kii.com/api/apps/{APP_ID}/things/{THING_ID}/ownership/cofirm" \
  -d '{
        "code": "XXXXXXXXXXX"
      }'

The access token required when validating the PIN code depends on who has requested the PIN code.

• If the thing requested the PIN code (i.e. the flow is initiated by the thing), then you must use the access token of the target user or the group member.

• If the target user or the group member requested the PIN code (i.e. the flow is initiated by the mobile app), then you must use the access token of the thing.

Kii Cloud will validate the PIN code. If successful, a 204 response is returned.

Checking the Ownership

A thing, app admin and any authenticated users can check if a certain user or group owns the thing.

A thing and app admin can check for all users.

A user (including a thing owner) can only check the user himself or the group in which the user belongs.

This example is checking if the specified user owns the thing.

curl -v -X HEAD \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  "https://api-jp.kii.com/api/apps/{APP_ID}/things/{THING_ID}/ownership/user:{USER_ID}"

The next example is checking if the specific group owns the thing.

curl -v -X HEAD \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  "https://api-jp.kii.com/api/apps/{APP_ID}/things/{THING_ID}/ownership/group:{GROUP_ID}"

If the specified user or group owns the thing, a 204 response is returned. If they do not own the thing, a 404 response is returned instead.

Getting a List of Owners

A thing and app admin can get a list of all users and groups who currently own the thing.

This is an example of how you get the list of thing owners.

curl -v -X GET \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  "https://api-jp.kii.com/api/apps/{APP_ID}/things/{THING_ID}/ownership"

The list is returned as follows:

200 OK

Content-type: application/vnd.kii.ThingOwnershipRetrievalResponse+json

{
  "users" : [ "0267251d9d60-7a09-4e11-ca44-068167c6" ],
  "groups" : [ "d5kl1xaf643lekoi6ur6999c1" ]
}

Removing the Ownership

A user (including a thing owner) can remove his thing ownership. A group member can remove the ownership of the group. The app admin can remove the ownership of any users and groups.

This example is removing the ownership of a user.

curl -v -X DELETE \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  "https://api-jp.kii.com/api/apps/{APP_ID}/things/{THING_ID}/ownership/user:{USER_ID}"

The next example is removing the ownership of a group.

curl -v -X DELETE \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  "https://api-jp.kii.com/api/apps/{APP_ID}/things/{THING_ID}/ownership/group:{GROUP_ID}"

If successful, a 204 response is returned.