Location
/api/apps/{appID}/users/{accountType}:{address}/topics/{topicID}/acl
This is the Access Control List of the topic.
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 topic:
- SUBSCRIBE_TO_TOPIC: Subscribe oneself to the topic and start receiving messages sent to the topic.
- SEND_MESSAGE_TO_TOPIC: Send a message to the topic.
Request Headers (Applies to all methods)
Authorization
header
Required: Yes
GET
/api/apps/{appID}/users/{accountType}:{address}/topics/{topicID}/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.
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.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.TopicNotFoundException+json
The topic was not found.
Contents
| Name | Type | Description |
|---|---|---|
| errorCode | string | Error code "TOPIC_NOT_FOUND". |
| message | string | The error message. |
| topicID | string | The ID of the topic that is not found |
| objectScope | ObjectScope | The scope of the topic |
| appID | string | The ID of the application. |
| userID | string | The ID of the user. Only provided for a user-scope bucket. |
| groupID | string | The ID of the group. Only provided for a group-scope bucket. |
| thingID | string | The ID of the thing. Only provided for a thing-scope bucket. |
| type | string | One of "APP", "APP_AND_USER", "APP_AND_GROUP", or "APP_AND_THING". |
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). |