ACL

Location /api/apps/{appID}/things/VENDOR_THING_ID:{vendorThingID}/acl

This is the Access Control List of the thing scope.

An ACL entry defines a permission (verb) granted or revoked for a subject over a resource. The permission is rejected by default, so you need to add ACL entries for granting accesses to Kii Cloud and your resources.

An ACL entry is composed of a resource, a subject, and a verb.

Subject: A subject can be either a user, a thing, or a group. Also, the following two "Special Users" can be set as a subject:

  • ANONYMOUS_USER: Represent all users who are accessing anonymously. This user cannot be used for topics.
  • ANY_AUTHENTICATED_USER: Represent any users who are authenticated.

Verb: These are the available verbs for a thing scope:

  • CREATE_NEW_BUCKET: Create a new bucket in the thing scope.
  • CREATE_NEW_TOPIC: Create a new topic in the thing scope.

Request Headers (Applies to all methods)

Authorization
header
Required: Yes

GET

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

Description

Retrieve all ACL entries.

Security

The administrator can always perform this action.
For other users, actors who can perform this action depends on the target resource:

  • User scope: the user.
  • Group scope: the group owner.
  • Thing scope: the thing or a thing owner.
  • Bucket: the scope owner.
  • Object: the scope owner and the object owner.
  • Topic: the scope owner and the topic creator.

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

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

The ACL entries have been successfully retrieved. The response is a JSON object that represents a map in which the key is a verb and the value is a JSON array of subjects.
Contents
Name Type Description
CREATE_NEW_BUCKET ACLSubject Permitted subjects to create new buckets.
An array of subjects to whom this action is permitted. Each subject is represented by a JSON object with the format `{ "userID": "{PERMITTED USER ID}" }` for the user permission or `{ "groupID": "{PERMITTED GROUP ID}" }` for the group permission.
CREATE_NEW_TOPIC ACLSubject Permitted subjects to create new topics.
An array of subjects to whom this action is permitted. Each subject is represented by a JSON object with the format `{ "userID": "{PERMITTED USER ID}" }` for the user permission or `{ "groupID": "{PERMITTED GROUP ID}" }` for the group permission.
QUERY_OBJECTS_IN_BUCKET ACLSubject Permitted subjects to query objects in this bucket.
An array of subjects to whom this action is permitted. Each subject is represented by a JSON object with the format `{ "userID": "{PERMITTED USER ID}" }` for the user permission or `{ "groupID": "{PERMITTED GROUP ID}" }` for the group permission.
READ_OBJECTS_IN_BUCKET ACLSubject Permitted subjects to read the content of the objects in this bucket.
An array of subjects to whom this action is permitted. Each subject is represented by a JSON object with the format `{ "userID": "{PERMITTED USER ID}" }` for the user permission or `{ "groupID": "{PERMITTED GROUP ID}" }` for the group permission.
CREATE_OBJECTS_IN_BUCKET ACLSubject Permitted subjects to create objects in this bucket.
An array of subjects to whom this action is permitted. Each subject is represented by a JSON object with the format `{ "userID": "{PERMITTED USER ID}" }` for the user permission or `{ "groupID": "{PERMITTED GROUP ID}" }` for the group permission.
DROP_BUCKET_WITH_ALL_CONTENT ACLSubject Permitted subjects to drop this bucket with all contents.
An array of subjects to whom this action is permitted. Each subject is represented by a JSON object with the format `{ "userID": "{PERMITTED USER ID}" }` for the user permission or `{ "groupID": "{PERMITTED GROUP ID}" }` for the group permission.
READ_EXISTING_OBJECT ACLSubject Permitted subjects to read existing objects.
An array of subjects to whom this action is permitted. Each subject is represented by a JSON object with the format `{ "userID": "{PERMITTED USER ID}" }` for the user permission or `{ "groupID": "{PERMITTED GROUP ID}" }` for the group permission.
WRITE_EXISTING_OBJECT ACLSubject Permitted subjects to write and update existing objects.
An array of subjects to whom this action is permitted. Each subject is represented by a JSON object with the format `{ "userID": "{PERMITTED USER ID}" }` for the user permission or `{ "groupID": "{PERMITTED GROUP ID}" }` for the group permission.
SUBSCRIBE_TO_TOPIC ACLSubject Permitted subjects to subscribe to this topic.
An array of subjects to whom this action is permitted. Each subject is represented by a JSON object with the format `{ "userID": "{PERMITTED USER ID}" }` for the user permission or `{ "groupID": "{PERMITTED GROUP ID}" }` for the group permission.
SEND_MESSAGE_TO_TOPIC ACLSubject Permitted subjects to send messages to this topic.
An array of subjects to whom this action is permitted. Each subject is represented by a JSON object with the format `{ "userID": "{PERMITTED USER ID}" }` for the user permission or `{ "groupID": "{PERMITTED GROUP ID}" }` for the group permission.
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 read the ACL of the target resource.
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).