Back to top

Introduction to the Sharing API v2 

Start with our v1 Core API docs for an introduction to the Kloudless API and more information on connecting user accounts and performing API requests.

Once an account is connected to your application, your application can perform API requests to the Sharing API endpoints listed below.

Overview

The Kloudless Sharing API provides unified access to object sharing capabilities, such as collaboration permissions and links.

The Sharing API has the following available object types:

  • permission

Each of these objects types is documented below, with their standard Kloudless attributes listed.


Permissions 

A Permission object defines access permissions for users and groups to objects.

Permission information for individual objects can be obtained via those objects’ endpoints. The objects currently supported are:

Individual Permission objects can be created, updated, or removed via this API’s endpoints.

The targets currently supported to grant access to are:

  • Team API

    • user: User
  • Email Address

Each Permission object has the following attributes:

  • id Unique identifier for the Permission object.

  • capabilities An object with attributes representing the approximate capabilities the target possesses when accessing the object. The value of each attribute is a boolean. Here are the possible unified capabilities included:

    • 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) include:
    • add: The container can be added to.
    • list: The containers contents can be listed. An approximation is provided if an exact match is unavailable. Please retrieve the object’s raw data for more granular service-specific information.
  • target A user, group, or domain Team API object granted access.

    • id The ID of the target, if available.
    • name The name of the target, if available.
    • email The email address of the target, if available.
    • type The type of the target: user, group, or domain.
    • api Always team.
  • status Optional. Indicates the status of the invitation to collaborate on the object, if one is present and this information is available. One of:

    • accepted
    • pending
    • rejected
  • created An ISO 8601 timestamp indicating when the Permission` object was created.

  • modified An ISO 8601 timestamp indicating when the Permission object was last modified.

  • type This object’s type. Always permission.

  • api Always sharing.

Supported services differ in availability of permission data. Services currently supported are:

  • box

    • Supports shared folders.
  • gdrive

    • Supports shared files and folders.
    • Team Drives support not yet available.
  • dropbox

    • Supports shared files, folders and team folders.
  • sharepoint

    • Supports shared files and folders.
  • onedrivebiz

    • Supports shared files and folders.

Create a Permission 

create a permissionPOST /accounts/{account_id}/sharing/permissions/

Permission objects can be created to grant access to objects to others. If a Permission object already exists for the target object, we will update the existing Permission object with the new Permission information.

To create a Permission object, send a JSON object to the API endpoint with the following attributes:

  • object: Required. Information identifying the object to grant access to.

    • id: The Kloudless ID of the object.
    • type The type of the object. e.g. file, folder, etc.
  • role: Required. The level of access to provide. An approximate role is used if an exact match is unavailable. Pass-through API requests can be used for granular service-specific sharing. Here are possible values for the role and the corresponding capabilities they provide:

    • previewer: preview. Grants limited read access to preview or view the object.
    • reader: download and list in addition to the above. Grants access to view, download, comment, list, and link to the object.
    • writer: edit, add, and share in addition to the above. Grants object editing and sharing capabilities.
    • owner: manage in addition to the above. Assigns ownership of the object.
  • target: Required. Information identifying the object access is being granted to. One of id or email must be provided.

    • id: The ID of the target.
    • email: The email address of the target.
    • type: The type of the target. e.g. user, group, or domain.

Here is an example request:

curl -H 'Authorization: Bearer [TOKEN]' \
    -H 'Content-Type: application/json' \
    -XPOST -d '{
        "object": {
            "id": "file_id",
            "type": "file"
        }
        "role": "reader",
        "target": {
            "id": "user_id",
            "type": "user"
        }
    }' \
    'https://api.kloudless.com/v2/accounts/15/sharing/permissions/'

Above, a user is being granted read access to a file. The response will contain the new Permission object’s information.

  • RequestToggle
  • Headers
    Authorization: Bearer [TOKEN]
    Content-Type: application/json
    Body
    {
        "object": {
            "id": "file_id",
            "type": "file"
        }
        "role": "reader",
        "target": {
            "email": "user_id@test.com",
            "type": "user"
        }
        "role": "reader"
    }
  • Response  201Toggle
  • Headers
    Content-Type: application/json
    Body
    {
      "id": "hLmV20jbvbGRag=",
      "type": "permission",
      "api": "sharing",
      "capabilities": {
        "preview": true,
        "download": true,
        "edit": false,
        "share": false,
        "manage": false
      },
      "target": {
        "id": "uGWK298eguSG2==",
        "email": "user_id@test.com",
        "name": "User A",
        "type": "user",
        "api": "team"
      },
      "modified": "2015-02-21T012:00:31.7301Z",
      "created": "2015-01-22T08:15:30.424173Z",
      "status": "pending"
    }

Update a Permission 

update a permissionPATCH /accounts/{account_id}/sharing/permissions/{permission_id}

To update a Permission object, send a JSON object with the following attributes:

The updated Permission object will be returned on success.

Here is an example request:

curl -H 'Authorization: Bearer [TOKEN]' \
    -H 'Content-Type: application/json' \
    -XPATCH -d '{
        "role": "writer",
    }' \
    'https://api.kloudless.com/v2/accounts/15/sharing/permissions/hLmV20jbvbGRag='
  • RequestToggle
  • Headers
    Authorization: Bearer [TOKEN]
    Content-Type: application/json
    Body
    {
      "role": "writer"
    }
  • Response  200Toggle
  • Headers
    Content-Type: application/json
    Body
    {
      "id": "hLmV20jbvbGRag=",
      "type": "permission",
      "api": "sharing",
      "capabilities": {
        "preview": true,
        "download": true,
        "edit": true,
        "share": true,
        "manage": false
      },
      "target": {
        "id": "uGWK298eguSG2==",
        "email": "user_id@test.com",
        "name": "User A",
        "type": "user",
        "api": "team"
      },
      "modified": "2015-02-21T012:00:31.7301Z",
      "created": "2015-01-22T08:15:30.424173Z",
      "status": "accept"
    }

Delete a Permission 

delete a PermissionDELETE /accounts/{account_id}/sharing/permissions/{permission_id}

Access to an object can be revoked by deleting the corresponding Permission object.

Here is an example request:

curl -L -H 'Authorization: Bearer [TOKEN]' \
    -XDELETE 'https://api.kloudless.com/v2/accounts/15/sharing/permissions/hLmV20jbvbGRag='
  • Response  204