Customizing a Scope's ACL

You can change who can add buckets and topics to a certain scope by modifying its ACL.

Scope ACL entries

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

• Action

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

  Action	What the target user/group/thing can execute
  CREATE_NEW_BUCKET	Create new buckets in the scope.
  CREATE_NEW_TOPIC	Create new topics in the scope.

• 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 scope" in the URL as follows. The URL also includes the action and subject:

• Application scope:

  https://api-jp.kii.com/api/apps/{APP_ID}/acl/{ACTION}/{SUBJECT}
  You need to present the app administrator token (See Admin Features).

• Group scope:

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

• User scope:

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

• Thing scope:

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

Managing a scope's ACL

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

Adding a scope ACL entry

Here is a sample API call for adding an ACL entry to the ACL of the application scope. In this example, the CREATE_NEW_TOPIC action is permitted to ANONYMOUS_USER.

curl -v -X PUT \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  "https://api-jp.kii.com/api/apps/{APP_ID}/acl/CREATE_NEW_BUCKET/UserID:ANONYMOUS_USER" \
  -d ""

You can do the same in other scopes by specifying the corresponding URL.

Deleting a scope ACL entry

To revoke an action that was allowed before, send a DELETE request for the target ACL entry.

In this example, we delete the ACL entry of the CREATE_NEW_TOPIC permitted to ANY_AUTHENTICATED_USER in the application scope.

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

You can do the same for other scopes by specifying the corresponding URL.

You may want to delete the ACL entry of the CREATE_NEW_BUCKET action permitted to ANY_AUTHENTICATED_USER in the application scope right after developing a new application. This will prevent users from misusing your application (i.e. creating new buckets).

Some of the default ACL entries cannot be deleted. See Cannot delete default ACL entries of scope owners and creators for more details.

Getting a scope's ACL

To get the ACL set on a scope, 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 CREATE_NEW_BUCKET action in the application scope.

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

The next example gets a list of all ACL entries in the ACL of the application scope.

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

Both examples specify the application scope. To get the ACL of any other scope, specify the corresponding URL.

Troubleshooting

• I cannot delete an ACL entry

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

• I cannot change the ACL of the application scope

  Changing the ACL of the application scope requires the app administrator privilege. Follow the procedure described in Admin Features to get an app administrator token and use it in the change request.

  See the table in Scope Access Control to learn more about the users who can change the ACL.