Customizing a Topic's ACL

You can customize the users who can subscribe and send messages to a topic by modifying the topic's ACL. This topic explains how you can do this.

In order to customize the permission to create topics, you need to change the ACL of the scope in which topics are to be created.

Topic ACL entries

A topic ACL entry is composed of an action and a subject:

  • Action

    This item defines "what" the target user or group can execute.

    Action What the target user/group/thing can execute
    SUBSCRIBE_TO_TOPIC Subscribe to the topic.
    SEND_MESSAGE_TO_TOPIC Send push messages to the topic.

  • Subject

    This item defines "who" can execute.

    Subject Who can execute the designated action?
    UserID:{USER_ID} The specified user.
    GroupID:{GROUP_ID} The members of the specified group.
    ThingID:{THING_ID} The specified thing.
    UserID:ANY_AUTHENTICATED_USER Any authenticated users.
    UserID:ANONYMOUS_USER Anonymous users.

    See Subject for the definition of the "Any authenticated users" and "Anonymous users".

You then specify the "target topic" in the URL as follows. The URL also includes the action and subject:

  • In the application scope:

    https://api-jp.kii.com/api/apps/{APP_ID}/topics/{TOPIC_ID}/acl/{ACTION}/{SUBJECT}
    You need to present the access token of the topic creator.

  • In a group scope:

    https://api-jp.kii.com/api/apps/{APP_ID}/groups/{GROUP_ID}/topics/{TOPIC_ID}/acl/ {ACTION}/{SUBJECT}
    You need to present the access token of the group owner or the topic creator.

  • In a user scope:

    https://api-jp.kii.com/api/apps/{APP_ID}/users/{USER_ID}/topics/{TOPIC_ID}/acl/ {ACTION}/{SUBJECT}
    https://api-jp.kii.com/api/apps/{APP_ID}/users/me/topics/{TOPIC_ID}/acl/{ACTION}/{SUBJECT}
    You need to present the access token of the scope owner or the topic creator.

  • IN a thing scope:

    https://api-jp.kii.com/api/apps/{APP_ID}/things/VENDOR_THING_ID:{VENDOR_THING_ID}/ topics/{TOPIC_ID}/acl/{ACTION}/{SUBJECT}
    https://api-jp.kii.com/api/apps/{APP_ID}/things/{THING_ID}/topics/{TOPIC_ID}/acl/ {ACTION}/{SUBJECT}
    You need to present the access token of the thing, thing owner, or the topic creator.

Managing a topic's ACL

You can add and delete an ACL entry in a topic's ACL. You can also get a list of ACL entries.

Adding a topic ACL entry

The first curl execution sample will add an ACL entry as below to the ACL of the group-scope topic GroupTopic.

  • Permit the "subscribe to the topic" action to "all authenticated users"

Note that this change corresponds to the first scenario presented in Changing a topic's ACL.

curl -v -X PUT \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  "https://api-jp.kii.com/api/apps/{APP_ID}/groups/{GROUP_ID}/topics/GroupTopic/acl/SUBSCRIBE_TO_TOPIC/UserID:ANY_AUTHENTICATED_USER" \
  -d ""

The next curl execution samples will add ACL entries as below to the ACL of the group-scope topic GroupTopic.

  • Permit the "subscribe to the topic" action to the user {USER_ID}.
  • Permit the "send push messages to the topic" action to the user {USER_ID}.

Note that these changes correspond to the second scenario presented in Changing a topic's ACL.

curl -v -X PUT \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  "https://api-jp.kii.com/api/apps/{APP_ID}/groups/{GROUP_ID}/topics/GroupTopic/acl/SUBSCRIBE_TO_TOPIC/UserID:{USER_ID}" \
  -d ""

curl -v -X PUT \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  "https://api-jp.kii.com/api/apps/{APP_ID}/groups/{GROUP_ID}/topics/GroupTopic/acl/SEND_MESSAGE_TO_TOPIC/UserID:{USER_ID}" \
  -d ""

The third curl execution sample will add an ACL entry as below to the ACL of the user-scope topic MyTODO.

  • Permit the "subscribe to the topic" action to the members of the group {GROUP_ID}.

Note that this change corresponds to the third scenario presented in Changing a topic's ACL.

curl -v -X PUT \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  "https://api-jp.kii.com/api/apps/{APP_ID}/users/{USER_ID}/topics/MyTODO/acl/SUBSCRIBE_TO_TOPIC/GroupID:{GROUP_ID}" \
  -d ""

Kii Cloud will return the following response:

  • Returns a 204 response if the ACL entry is successfully accepted.
  • Returns a 404 response with the error code TOPIC_NOT_FOUND if the specified topic does not exist.
  • Returns a 409 response with the error code ACL_ALREADY_EXISTS if the same ACL entry already exists.

Deleting a topic ACL entry

To delete an ACL entry, send a DELETE request for the target ACL entry.

In this example, we delete an ACL entry of the SUBSCRIBE_TO_TOPIC action permitted to ANY_AUTHENTICATED_USER.

curl -v -X DELETE \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  "https://api-jp.kii.com/api/apps/{APP_ID}/groups/{GROUP_ID}/topics/GroupTopic/acl/SUBSCRIBE_TO_TOPIC/UserID:ANY_AUTHENTICATED_USER"

You can delete ACL entries in other scopes by specifying the corresponding URL.

Getting a topic's ACL

To get the ACL set on a topic, send a GET request to the corresponding URL with no action or subject.

The following example gets a list of all subjects who are permitted the SUBSCRIBE_TO_TOPIC action.

curl -v -X GET \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  "https://api-jp.kii.com/api/apps/{APP_ID}/groups/{GROUP_ID}/topics/GroupTopic/acl/SUBSCRIBE_TO_TOPIC"

The next example gets a list of all ACL entries in the topic's ACL.

curl -v -X GET \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  "https://api-jp.kii.com/api/apps/{APP_ID}/groups/{GROUP_ID}/topics/GroupTopic/acl"

Both examples specify a group-scope topic. To get the ACL of a topic in any other scope, please specify the corresponding URL.

Troubleshooting

I cannot delete an ACL entry

You cannot delete default ACL entries applied to scope owners and topic creators. See Cannot delete default ACL entries of scope owners and creators for more details.