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.

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 object type is documented below, with its 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: All capabilities above.

  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.
  • Shared Drives support not yet available.

• onedrivebiz

  • Supports shared files and folders.

• sharepoint

  • Supports shared files and folders.

• sharefile

  • Supports shared folders.

• smb

  • Supports shared files and folders.
  • Use the X-Kloudless-Raw-Data: true header to retrieve more information, including:
    • the ACE Type (either access_allowed or access_denied)
    • the target’s SID
    • booleans representing individual ACE Flags,
    • booleans representing individual masks in the File or Folder Access Mask.
    • the raw binary Access Mask and ACE Flags
  • The Permission IDs may change as they depend on the ordering, so be sure to retrieve the list of Permissions immediately prior to updating any individual Permission, in order to use the correct Permission ID during the update.
  • To set or update SMB ACLs, provide the raw object in the POST/PATCH request in the same format returned in the response when retrieving ACLs. For example, include the raw.object property, or the capabilities.raw.object property that contains information on the ACE type, ACE flags, and access mask.

    • {
        "object": {
            "id": "file_L1NNQi9jYXRjYXQuanBn",
            "type": "file"
        },
        "raw": {
          "object": {
            "type": 0,
            "flags": 0,
            "mask": 2032127,
            "sid": "S-1-1-0"
          }
        }
      }

    • {
        "object": {
            "id": "file_L1NNQi9jYXRjYXQuanBn",
            "type": "file"
        },
        "capabilities": {
          "raw": {
            "object": {
              "ace_type": "access_allowed",
              "ace_flags": {
                "object_inherit": false,
                "container_inherit": false,
                "no_propagate_inherit": false,
                "inherit_only": false,
                "inherited": true
              },
              "access_mask": {
                "file_read_data": true,
                "file_write_data": true,
                "file_append_data": true,
                "file_read_ea": true,
                "file_write_ea": true,
                "file_execute": true,
                "file_delete_child": true,
                "file_read_attributes": true,
                "file_write_attributes": true,
                "delete": true,
                "read_control": true,
                "write_dac": true,
                "write_owner": true,
                "access_system_security": false,
                "maximum_allowed": false,
                "generic_all": false,
                "generic_execute": false,
                "generic_write": false,
                "generic_read": false
              }
            }
          }
        },
        "target": {
          "type": "unknown",
          "id": "unknown_Uy0xLTEtMA",
          "raw": {
            "id": "S-1-1-0"
          }
        }
      }

List File Permissions 

List Folder Permissions 

Create a Permission 

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/'

Update a Permission 

curl -H 'Authorization: Bearer [TOKEN]' \
    -H 'Content-Type: application/json' \
    -XPATCH -d '{
        "role": "writer",
    }' \
    'https://api.kloudless.com/v2/accounts/15/sharing/permissions/hLmV20jbvbGRag='

Delete a Permission 

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

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: All capabilities above.

  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.

• sharepoint

  • Supports file/folder link listing.

List File Storage Links 

List Folder Storage Links 

Delete Link