Customizing a KiiObject's ACL

You can change the access control applied to a KiiObject by setting its ACL.

KiiObject ACL entries

A KiiObject 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
    READ_EXISTING_OBJECT Read the KiiObject.
    WRITE_EXISTING_OBJECT Update and delete the KiiObject.

    Note: The "READ_OBJECTS_IN_BUCKET" action set to a bucket's ACL allows the subject to unconditionally read all KiiObjects in the bucket, even if they are not permitted the "READ_EXISTING_OBJECT" action on the KiiObjects in the bucket. For understanding how the action works, see ACL Customization Examples.

  • 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 KiiObject 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}/buckets/{BUCKET_ID}/objects/{OBJECT_ID}/acl/ {ACTION}/{SUBJECT}
    You need to present the access token of the KiiObject creator.

  • In a group scope:

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

  • In a user scope:

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

  • In a thing scope:

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

Managing a KiiObject's ACL

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

Adding a KiiObject ACL entry

Here are sample API calls for permitting the READ_EXISTING_OBJECT action to various subjects.

Permitting the READ_EXISTING_OBJECT action to ANONYMOUS_USER

curl -v -X PUT \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  "https://api-jp.kii.com/api/apps/{APP_ID}/users/{USER_ID}/buckets/{BUCKET_ID}/objects/{OBJECT_ID}/acl/READ_EXISTING_OBJECT/UserID:ANONYMOUS_USER"

Permitting the READ_EXISTING_OBJECT action to ANY_AUTHENTICATED_USER

curl -v -X PUT \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  "https://api-jp.kii.com/api/apps/{APP_ID}/users/{USER_ID}/buckets/{BUCKET_ID}/objects/{OBJECT_ID}/acl/READ_EXISTING_OBJECT/UserID:ANY_AUTHENTICATED_USER"

Permitting the READ_EXISTING_OBJECT action to a group

curl -v -X PUT \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  "https://api-jp.kii.com/api/apps/{APP_ID}/users/{USER_ID}/buckets/{BUCKET_ID}/objects/{OBJECT_ID}/acl/READ_EXISTING_OBJECT/GroupID:{GROUP_ID}"

Permitting the READ_EXISTING_OBJECT action to a user

curl -v -X PUT \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  "https://api-jp.kii.com/api/apps/{APP_ID}/users/{USER_ID}/buckets/{BUCKET_ID}/objects/{OBJECT_ID}/acl/READ_EXISTING_OBJECT/UserID:{USER_ID}"

Permitting the READ_EXISTING_OBJECT action to a thing

curl -v -X PUT \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  "https://api-jp.kii.com/api/apps/{APP_ID}/users/{USER_ID}/buckets/{BUCKET_ID}/objects/{OBJECT_ID}/acl/READ_EXISTING_OBJECT/ThingID:{THING_ID}"

Deleting a KiiObject ACL entry

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

In this example, we delete an ACL entry of the WRITE_EXISTING_OBJECT action permitted to ANONYMOUS_USER.

curl -v -X DELETE \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  "https://api-jp.kii.com/api/apps/{APP_ID}/users/{USER_ID}/buckets/{BUCKET_ID}/objects/{OBJECT_ID}/acl/WRITE_EXISTING_OBJECT/UserID:ANONYMOUS_USER"

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

Getting a KiiObject's ACL

To get the ACL set on a KiiObject, 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 WRITE_EXISTING_OBJECT action.

curl -v -X GET \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  "https://api-jp.kii.com/api/apps/{APP_ID}/users/{USER_ID}/buckets/{BUCKET_ID}/objects/{OBJECT_ID}/acl/WRITE_EXISTING_OBJECT"

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

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

Both examples specify a KiiObject in a user scope. To get the ACL of a KiiObject in the other scopes, specify the corresponding URL.

Troubleshooting

I cannot delete an ACL entry

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