The Kloudless v2 Sharing API is a new set of API endpoints related to collaboration permissions that can be used with Storage connectors today. Compared to v1, the v2 Sharing API represents a much more detailed first-class representation of collaboration permissions on objects such as files and folders across various cloud services.

The v2 Sharing API currently supports creating, updating, and deleting access control settings across popular cloud storage services with a single implementation. We plan to expand this capability to support accessing collaboration settings for other types of objects in the future.

Reasons to upgrade to v2

In the v1 Storage API, only file and folder objects are first-class resources. The v1 Storage API offers permission endpoints to retrieve, modify and delete access via endpoints nested under file and folder resources. This limits how easily permission objects can be retrieved and manipulated for other resource types. It also causes duplication of endpoints beneath each resource.

In addition, the v1 Permission Object’s type values could either be user or group. This is inaccurate as it indicates that the object could be a User or Group, whereas the object actually describes collaboration permissions.

We discovered the most popular use case for altering collaboration settings was to share newly uploaded files. Based on this usage pattern, and the limitations described above, we decided to make Permission Objects first-class resources in the v2 API. This means that an account’s collaboration data can be altered without constructing a URL that nests the data under other resource types, such as files or folders.

Now let’s try out some API requests!

Examples

Sharing a file

Here we show how to create a Permission object associated with a File, to share that file:

1. Get the FILE_ID from the Storage API. For example, by listing folder contents.
2. Get the USER_ID you wish to manage access to the file for. For example, by listing users (or groups) from the Team API.
3. Make a Create Permission request, specifying the role as reader as shown below.
   

Below is an example of a Permission object returned:

The new capabilities field describes the permission more accurately. The field’s attributes are unified across different upstream services. Here is what each represents:

• preview: The object can be viewed or previewed.
• download: The object can be downloaded.
• edit: The object can be edited.
• share: The object’s sharing permissions can be modified.
• manage: Capabilities specific to containers (e.g. folders).
• add: The container can be added to. For example, a folder that allows a file to be uploaded to it.
• list: The container’s contents can be listed.

An approximation is provided if an exact match is unavailable. The raw permission data can always be retrieved if further information is required by setting the X-Kloudless-Raw-Data header to true (docs).

Unsharing a file

Likewise, if we want to remove the user from accessing this resource, we simply extract the id and use it to initiate a Delete Permission request:

And poof! Managing resource permissions is easy with Kloudless API!

Related APIs

Check out our earlier blog post for a high-level overview of the v2 Audit Events API. The Audit Events API can be used together with the Sharing API to track changes to collaboration settings across all data in an organization. For example, the Audit Events API will return events describing permissions that are updated on any file in users’ Box accounts within a Box Enterprise organization. The event data includes the newly introduced first-class v2 Permission Objects, which can be managed using the Sharing API, and whose associated files can be accessed using the Storage API.

Try out the endpoints described above via our API Explorer today! We’d love to receive any feedback or questions at hello@kloudless.com.