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

  • link

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:

  • Storage API
    • file
    • folder

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.
  • dropbox

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

    • Supports folders.
    • Sharing a folder with an email address requires an admin account.
  • gdrive

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

    • Supports shared files and folders.
  • sharepoint

    • Supports shared files and folders.
  • sharefile

    • Supports shared folders.
  • smb

    • Supports listing permissions for shared files and folders.

List File Permissions 

list file permissionsGET /accounts/{account_id}/storage/files/{id}/permissions

File permissions determine which accounts are able to access the resource.

  • RequestToggle
  • Headers

    Authorization: Bearer [TOKEN]
  • Response  200Toggle
  • Headers

    Content-Type: application/json

    Body

    {
      "objects": [
        {
          "id": "fZGVycGRlcnAK",
          "type": "permission",
          "api": "sharing",
          "capabilities": {
            "preview": false,
            "download": true,
            "edit": false,
            "share": false,
            "manage": false
          },
          "target": {
            "id": "uZmFrZXVzZXIK",
            "type": "user"
          },
          "modified": "2015-02-21T012:00:31.7301Z",
          "created": "2015-01-22T08:15:30.424173Z",
          "status": "accepted"
        },
        {
          "id": "fZGVycGRlcnAK",
          "type": "permission",
          "api": "sharing",
          "capabilities": {
            "preview": false,
            "download": true,
            "edit": false,
            "share": false,
            "manage": false
          },
          "target": {
            "id": "gZ3JvdXBtZXJwCg==",
            "type": "user"
          },
          "modified": "2015-02-21T012:00:31.7301Z",
          "created": "2015-01-22T08:15:30.424173Z",
          "status": "accepted"
        }
      ],
      "type": "object_list",
      "api": "sharing"
    }

List Folder Permissions 

list folder permissionsGET /accounts/{account_id}/storage/folders/{id}/permissions

Folder permissions determine which accounts are able to access the resource.

  • RequestToggle
  • Headers

    Authorization: Bearer [TOKEN]
  • Response  200Toggle
  • Headers

    Content-Type: application/json

    Body

    {
      "objects": [
        {
          "id": "fZGVycGRlcnAK",
          "type": "permission",
          "api": "sharing",
          "capabilities": {
            "preview": true,
            "download": true,
            "edit": true,
            "share": false,
            "manage": false,
            "add": true,
            "list": true
          },
          "target": {
            "id": "uZmFrZXVzZXIK",
            "type": "user"
          },
          "password": false,
          "expiration": null,
          "modified": "2015-02-21T012:00:31.7301Z",
          "created": "2015-01-22T08:15:30.424173Z",
          "status": "accepted"
        },
        {
          "id": "fZGVycGRlcnAK",
          "type": "permission",
          "api": "sharing",
          "capabilities": {
            "preview": false,
            "download": true,
            "edit": false,
            "share": false,
            "manage": false,
            "add": false,
            "list": true
          },
          "target": {
            "id": "gZ3JvdXBtZXJwCg==",
            "type": "group"
          },
          "modified": "2015-02-21T012:00:31.7301Z",
          "created": "2015-01-22T08:15:30.424173Z",
          "status": "accepted"
        }
      ],
      "type": "object_list",
      "api": "sharing"
    }

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

Links 

A Link object represents a directly accessible hyperlink in the upstream service to a resource.

  • Storage API
    • file
    • folder
  • id Unique identifier for the Link object.

  • url The URL to view/download the object.

  • download_url The URL to only download the object, differs based on service.

  • resource The resource that the link refers to.

    • id The ID of the resource.
    • type The type of the resource.
  • 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 Optional. A user, group, or domain Team API object granted access. If a target isn’t specified, then the link is accessible without requiring an account in the underlying service.

    • 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.
  • expiration Optional. An ISO 8601 timestamp indicating when the link is no longer valid.

  • password A boolean value indicating whether the link is password protected. This is separate from authorization granted via the upstream accounts.

  • created An ISO 8601 timestamp indicating when the Link object was created.

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

  • type This object’s type. Always link.

  • api Always sharing.

Currently supported services are:

  • egnyte

    • Supports file link listing and deletion.
  • sharefile

    • Supports file link deletion. Link creation/modification information is currently only available via events.