Introduction to the Activity API 

Start with our 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 Activity API endpoints listed below.

Overview

The Kloudless Activity API helps monitor accounts using a variety of service-specific implementations to be aware of activity occurring within each account.

The services that provide activity for each API category are listed below.

Storage Activity

File-system activity data is available for the following services:

  • alfresco

  • alfresco_cloud

  • box

  • cmis

  • cq5

  • dropbox

  • dynamics

  • egnyte

  • evernote

  • gdrive

    • By default, Kloudless does not monitor Shared Drives’ activity for non-admin Google Drive accounts. To monitor specific folders, see the monitored_resources attribute of the Subscription object for more information.
  • hubspot

  • jive

  • onedrivebiz

  • s3

  • salesforce

    • Tracks Chatter files, Libraries, Documents and Attachments only.
  • sharefile

  • sharepoint

    • Tracks only the primary site collection’s Document Library in non-admin accounts.
    • Administrator accounts that connected through the admin OAuth flow with org-wide data access will have all its site collections activity tracked.
  • skydrive

  • smb

  • webdav

  • slack

    • Tracks Slack file, message, and conversation activity that the account has visibility into.
    • Org-wide Slack Enterprise Grid activity available in Slack Audit Logs API can be tracked with Audit activity.
  • procore

  • plangrid

  • autodesk

    • Due to limitations with Autodesk Webhooks API, Autodesk activity for each account is only tracked for one application at a time across all environments.
  • bluebeam

  • kapost

    • Activity is only tracked for changes to Kapost Content objects.

CRM Activity

CRM activity data is available for the following services:

  • salesforce

    • Tracks all custom objects (up to the maximum limit). A subset of standard objects are monitored via the Streaming API as well.
  • dynamics

    • Only tracks add and update activity for supported object types. Please contact Kloudless Support if you’re interested in tracking delete activity.

Calendar Activity

Calendar activity data is available for the following services:

  • google_calendar

    • Administrator google_calendar accounts currently behave similarly to non-admin accounts and do not monitor org-wide calendar activity. They should therefore not be used to exclusively monitor the authenticating user’s calendar activity. This will be updated in the future.
  • outlook_calendar, exchange

    • Modifications to past activity are not currently tracked.

By default, Kloudless will monitor the user’s primary calendar.

If you have specific calendars to monitor, see the monitored_resources attribute of the Subscription object for more information.

Email Activity

Email Message activity data is available for the following services:

  • gmail

    • Kloudless will monitor “All Mail” for activity.
  • outlook_email

    • Kloudless will monitor the user’s inbox folder.
  • exchange_email

    • Kloudless will monitor the user’s inbox folder.

Org-wide Activity

Org-wide activity tracking for all organization users is available for administrator accounts for the following services in Kloudless Enterprise:

Audit Activity

Audit activity can be retrieved through the normal activity endpoint, and will be available for administrator accounts for the following services:

  • azurerm

  • box

  • cloudtrail

  • dropbox

  • gdrive

    • Requires G Suite Enterprise.
  • onedrivebiz

  • sharepoint

  • slack

    • Requires Slack Enterprise Grid. Note that slack admin accounts prioritize providing org-wide activity, with granularity to the conversation level. To monitor message activity, either periodically list new messages in each Conversation (channel, private/group DM), or use a separate non-admin account to monitor activity in Conversations that the account has access to.

You can find the list of Kloudless Audit activity here. This activity provides additional audit-type information for the account.

v2: Check out our v2 Audit Activity API for a comprehensive solution to track org-wide activity occurring in business applications. The initial release includes support for popular services such as Office 365, G Suite, Box, Dropbox, Egnyte, and Sharefile.

Activity latency

Activity data may not be provided right away. Latency prior to an update is configurable in self-hosted/private Kloudless Enterprise installations and varies in the cloud version as detailed below.

The following services notify Kloudless of changes to users’ accounts, with activity data updated in at most 1.5 minutes:

  • box

  • dropbox

  • evernote

  • gdrive

  • s3

    • New buckets are detected every 20 min.
  • smb

  • salesforce

  • google_calendar

  • outlook_calendar

  • sharefile

  • gmail

  • procore

  • autodesk

Other services require that we query the service repeatedly to find changes. This means that for the following services, activity data on average will be updated every 5 minutes on Kloudless’ cloud version, and every 1 minute in Kloudless Enterprise:

  • File-system traversal or equivalent

    • cq5
    • hubspot
    • jive
    • salesforce
    • webdav
    • plangrid
    • bluebeam
  • Polling an API endpoint or equivalent

    • egnyte
    • sharefile
      • Polling is used for non-audit type activity collected for non-admin accounts.
    • sharepoint
      • Polling is used for non-audit type activity collected for non-admin accounts.
      • For Audit activity, latencies vary between Office 365 workloads. SharePoint, OneDrive for Business, and Azure Login activity are available within minutes. Others are documented here.
    • skydrive
    • onedrivebiz
      • See sharepoint.
    • outlook_email
    • exchange_email

The CMIS-like services listed below also poll for changes. To enable more efficient activity retrieval by Kloudless, please configure the repository to create a change log if possible.

  • alfresco

  • alfresco_cloud

  • cmis

  • documentum

  • filenet

Activity retention

Kloudless attempts to query activity data synchronously where available. This provides the most scalable approach as it avoids Kloudless having to cache activity information. However, as described when discussing latency, not all services support API endpoints to query activity information in real-time. Kloudless caches activity data temporarily for these services.

Up to 10,000 activity objects per account over the previous 24 hours are stored temporarily in Kloudless’ database for efficient retrieval by each application.

To determine which services adhere to this limit, query the publicly available Services metadata endpoint and check the events.events.persistence property as shown using curl and jq below for box:

curl -X GET 'https://api.kloudless.com/v1/public/services/box/' \
    | jq '.properties.requirements["events.events.persistence"][]?.result'

true means that Kloudless collects activity data in the background and caches it based on the retention period. The majority of services currently require this. Examples include Amazon S3 and Alfresco.

false means that Kloudless directly retrieves activity data and doesn’t need to cache any information. In this case, the cursors Kloudless returns when listing activity are still only valid for the retention period described above. By removing stale cursors, Kloudless ensures requests to list activity that include no cursor or stale cursors automatically use a cursor closest to the maximum retention period for services that do require retention. This allows consistent behavior across services. Otherwise, services returning false would return activity data from the beginning of time whereas ones returning true would return activity data based on the retention period. Here are services that Kloudless directly queries:

  • box

  • dropbox

  • exchange (calendar activity only)

  • exchange_email

  • gdrive

  • google_calendar

  • onedrivebiz (admin only)

  • outlook_calendar

  • outlook_email

  • sharepoint (admin only)

The absence of a result indicates that the service does not support activity monitoring.


Activity 

Overview

Actions such as creating, modifying, or deleting resources generate activity that we track. They are represented as a stream of Activity objects.

You need subscriptions to use Activity endpoints. To enable automatic subscriptions for your application, visit the Activity Monitoring Configuration page and ensure the checkbox for ‘Track Activity’ is checked. This creates default Subscription objects for any accounts connected or reconnected after this time automatically. With a default Subscription, you can use the default alias for the subscription_id when accessing the Subscription and Activity endpoints.

Alternately, you can create subscriptions by using Subscription endpoints. Please check Creating a Subscription.

Activity Attributes

Activity objects have the following attributes:

  • id: The id of the Activity object. May be None if activity are directly retrieved from the upstream service, or a string if the upstream activity ID is available. Will be a number representing the ID of the activity otherwise.

  • account: The id of the account the resource belongs to.

  • subscription: The id of the subscription the resource is monitored by.

  • modified: The time the activity occurred. This is not always precise due to the underlying service. Will be null if unavailable.

  • type: Any of the types described in Activity types.

  • ip: User’s IP Address, if available. May be null.

  • metadata: The new metadata of the resource or null if the action is delete and the data is unavailable.

  • previous_metadata: The metadata of the original resource prior to a rename, move, or copy. {} or absent if unavailable.

  • user_id: For admin accounts, this field specifies the ID of the user responsible for the activity.

Activity Types

Currently the following types of activity are available for objects belonging to the following APIs:

  • add: a resource has been created.

    • Resource’s API type: storage, crm, calendar, itsm, messaging, email.
  • delete: a resource has been deleted.

    • Resource’s API type: storage, crm, calendar, itsm, messaging, email.
  • update: a resource has been modified.

    • Resource’s API type: storage, crm, calendar, itsm, messaging, email.
  • rename: a resource has been renamed.

    • Resource’s API type: storage.
  • move: a resource has been moved.

    • Resource’s API type: storage.
  • copy: a resource has been copied.

    • Resource’s API type: storage.
  • restore: a resource has been restored after being deleted.

    • Resource’s API type: storage.

The CRM API activity applies to all standard Kloudless CRM objects. Activity data incidentally obtained for other CRM objects is also available during the process of activity retrieval as raw object data even if the data is not marshaled into the unified Kloudless API format.

The most specific activity is returned where possible; otherwise, the activity specified by the underlying service will be returned.

List Activity 

List activityGET /accounts/{account_id}/subscriptions/{subscription_id}/activity{?cursor,page_size,from,until}]

List activity monitored by this Subscription using this endpoint!

Activity occurring in an account is returned as a list of activity objects in the order that our system was made aware of them.

While there is a small chance that there will be duplicate activity in the activity stream, Kloudless takes steps to minimize duplicate activity where possible in order to properly reflect the current state of the monitored resources in the underlying upstream service. The net result of applying all activity should reflect the current state of the upstream service.

The response contains the following fields:

  • objects: List of the activity that has taken place. If no activity is available, then there are no objects left to paginate through using the cursor at this time.

  • cursor: A string identifying a location in the stream immediately after the activity described in objects.

  • count: Number of activity objects returned.

  • type: Will always be object_list.

  • api: Will always be activity.

The returned cursor should be used in subsequent requests so that only activity that has not been seen previously is returned.

Use the default alias to access the default Subscription’s activity as shown in this example request:

curl -H 'Authorization: Bearer [TOKEN]' \
    'https://api.kloudless.com/v1/accounts/me/subscriptions/default/activity?cursor=121'

Time-Based Activity Retrieval

The parameters from and until retrieve activity within a specific time range directly from the upstream service. This is available for the following services:

  • box (admin only)

  • sharepoint (admin only)

  • onedrivebiz (admin only)

  • dropbox (admin only)

  • gdrive (admin only)

The cursor returned in the response is limited in range to the time range specified in the initial request. It cannot be used in conjunction with the parameters from and until in future requests as the range cannot be altered.

If an empty list of activity is returned, there is no activity within the time range specified, or after the cursor specified.

  • Parameters:

    • cursor (optional, string) … The last cursor in the activity stream that the application has seen. This can be retrieved from last_cursor returned in the subscription object if not known. The cursor can also be set to after-auth, which will retrieve activity that has occurred after the account was connected. This is useful if prior activity is unnecessary.

      This parameter cannot be used with from and until. Subsequent cursors returned by a request using those parameters will be restricted to the time range specified in the first request.

    • page_size = 1000 (optional, number) … Number of activity objects in the stream to return, if available. The page_size must be greater than or equal to 1 and less than or equal to 1000. Treated as advisory.

    • from (optional, string) … An ISO-8601 string specifying the time of the oldest activity in the range to return (inclusive). Can be used without until.

    • until (optional, string) … An ISO-8601 string specifying the latest time prior to which to return activity (exclusive). Must be used along with from. Non-overlapping queries can be performed since the activity times are in the range [from, until). Future cursor values returned are limited in range to the until value provided in the first request.

  • Response  200Toggle
  • Headers

    Content-Type: application/json

    Body

    {
      "cursor": 330,
      "count": 5,
      "objects": [
        {
          "metadata": {
            "size": 5422,
            "mime_type": "image/png",
            "downloadable": true,
            "id": "Ffh__5fKqvbBc58zRvTe4KN3zhTSzmKoyLcQPUjAwr7-UoZmRQcmoKFNe5OZtFsmA_eKpgOPrEy6IqqE3K8klbw==",
            "type": "file",
            "account": 613076,
            "name": "logo_white_146x58.png",
            "parent": {
              "id": "FhUnU-Ri3DF0hQ5cU9wC7sTzChcbRsiEGuJ2g1sh5OcIbuF6JacDq7Ac7HsHC-mfC4Lkw-4MaaFHtv1CqwYlHGw==",
              "name": "Shared Documents"
            },
            "ancestors": null,
            "owner": {
                "id": "n1nNjHU4FP37p2VEmtZqmLQFN4BydJwiPV5YdiSqO="
            },
            "created": null,
            "modified": "2015-10-02T21:38:03Z",
            "path": "/Shared Documents/logo_white_146x58.png"
          },
          "action": "+",
          "account": 613076,
          "id": 320,
          "user_id": null,
          "type": "add",
          "previous_metadata": {},
        },
        {
          "metadata": {
            "size": 5391,
            "mime_type": "image/png",
            "downloadable": true,
            "id": "FYs8EY4mXgR6qgWYcEmocoygVtj1DUm29ABlZ-5tsmOSmdithPoA_yzYHlmpd6aFqTzxjVZOld0Uxud_l99Y7hw==",
            "type": "file",
            "account": 613076,
            "name": "test (2).png",
            "parent": {
              "id": "FhUnU-Ri3DF0hQ5cU9wC7sTzChcbRsiEGuJ2g1sh5OcIbuF6JacDq7Ac7HsHC-mfC4Lkw-4MaaFHtv1CqwYlHGw==",
              "name": "Shared Documents"
            },
            "ancestors": null,
            "owner": {
                "id": "rVzgcMEDWTNGchDV7FqDqzVKdqZSkEuCJjeOj="
            },
            "created": null,
            "modified": "2015-10-02T20:52:41Z",
            "path": "/Shared Documents/test (2).png"
          },
          "action": "+",
          "account": 613076,
          "id": 326,
          "user_id": null,
          "type": "add",
          "previous_metadata": {},
        },
        {
          "metadata": {
            "size": 5391,
            "mime_type": "image/png",
            "downloadable": true,
            "id": "FYs8EY4mXgR6qgWYcEmocoygVtj1DUm29ABlZ-5tsmOSmdithPoA_yzYHlmpd6aFqTzxjVZOld0Uxud_l99Y7hw==",
            "type": "file",
            "account": 613076,
            "name": "test (2).png",
            "parent": {
              "id": "FhUnU-Ri3DF0hQ5cU9wC7sTzChcbRsiEGuJ2g1sh5OcIbuF6JacDq7Ac7HsHC-mfC4Lkw-4MaaFHtv1CqwYlHGw==",
              "name": "Shared Documents"
            },
            "ancestors": null,
            "owner": {
                "id": "rVzgcMEDWTNGchDV7FqDqzVKdqZSkEuCJjeOj="
            },
            "created": null,
            "modified": "2015-10-02T20:52:45Z",
            "path": "/Shared Documents/test (2).png"
          },
          "account": 613076,
          "id": 330,
          "user_id": null,
          "type": "delete",
          "previous_metadata": {},
        },
        {
          "id": 132944,
          "account": 145,
          "modified": "2016-08-16T00:54:29.279000Z",
          "type": "add",
          "user_id": null,
          "ip": null,
          "metadata": {
            "id": 482938193,
            "name": "Kloudless, Inc.",
            "owner": "company@salesforce.com",
            "industry_code": 541519,
            "industry": Information Technology,
            "employees": 25,
            "rating": Hot,
            "email": hello@kloudless.com,
            "website": "kloudless.com",
            "created": "2015-09-02T10:11:33.948274Z",
            "modified": "2015-09-03T15:43:12.847532Z",
            "description": "Cloud API Services. Storage, CRM, and more",
            "type": account
          },
        },
        {
          "id": 132945
          "account": 145,
          "modified": "2016-08-16T00:54:29.279000Z",
          "type": "update",
          "user_id": "uMsO3tKSabQ0s1=",
          "ip": null,
          "metadata": {
            "id": 1928381283,
            "account": 482938193,
            "owner": "company@salesforce.com",
            "campaign": 14855,
            "lead": "3586",
            "name": "Eliot Sun",
            "title": "CEO",
            "department": "Execs",
            "email": "hello@kloudless.com",
            "created": "2015-10-01T02:34:57.123832Z",
            "modified": "2015-10-05T03:13:87.857364Z",
            "description": "CEO and Co-founder of Kloudless, Inc.",
            "type": contact
          },
        },
      ],
      "type": "object_list",
      "api": "activity",
    }
    {
      "count": 1,
      "cursor": 1408133596,
      "objects": [
        {
          "id": "LTYyMDQzOTYxNTQ2NTk3MTc3Nzk=",
          "account": 338476387,
          "action": "+",
          "ip": "36.228.22.224",
          "modified": "2019-09-23T09:33:00.099000Z",
          "type": "add",
          "user_id": "uMTAwMzYzNTk2Mzg5MzExODAxOTMw",
          "metadata": {
            "id": "FVSShlCqQFxa07HhjqSE3jMrhGi9ENP0qVxNwdVL1Na9WjesFbWopDueL-mJdBHgN",
            "raw_id": "1ZJJBK4ZrEQR7mVyr5hRK3M5URg-GxPL6",
            "created": null,
            "modified": "2019-09-23T09:33:00.099000Z",
            "name": "Copy of DogeCool.jpg",
            "type": "file",
            "size": null,
            "path": null,
            "mime_type": "image/jpeg",
            "owner": {
              "api": "team",
              "id": "uYWRtaW5AZGV2ZWxvcGVycy5rbG91ZGxlc3MuY29t",
              "type": "user",
              "calendar_id": null,
              "href": "https://api.kloudless.com/v1/accounts/338476387/team/users/uYWRtaW5AZGV2ZWxvcGVycy5rbG91ZGxlc3MuY29t",
              "email": "admin@developers.kloudless.com",
              "id_type": "login"
            },
            "last_modifier": {
              "api": "team",
              "id": "uMTAwMzYzNTk2Mzg5MzExODAxOTMw",
              "type": "user",
              "calendar_id": null,
              "href": "https://api.kloudless.com/v1/accounts/338476387/team/users/uMTAwMzYzNTk2Mzg5MzExODAxOTMw",
              "email": "admin@developers.kloudless.com",
              "id_type": "default"
            },
            "ancestors": null,
            "account": 338476387
          }
        }
      ],
      "type": "object_list",
      "api": "events"
    }

Audit Activity 

v2: Check out our v2 Audit Activity API for a comprehensive solution to track org-wide activity occurring in business applications. The initial release includes support for popular services such as Office 365, G Suite, Box, Dropbox, Egnyte, and Sharefile.

The previous v1 docs are available for reference in our v2 migration guide.


Subscriptions 

A Kloudless Subscription object enables monitoring an upstream service’s activity and receiving webhook notifications for it. Activity monitoring begins once a Subscription is created for an account.

To enable automatic subscriptions for your application, visit the Activity Monitoring Configuration page and ensure the checkbox for ‘Track Activity’ is checked. This creates default Subscription objects for any accounts connected or reconnected after this time automatically. With a default Subscription, you can use the default alias for the subscription_id when accessing the Subscription and Activity endpoints.

Kloudless Subscriptions have the attributes below:

  • id Unique identifier for this Subscription. default can be used as an alias for the id of the Subscription that has default set to true.

  • account Account identifier this Subscription belongs to.

  • expiry ISO 8601 timestamp for when the Subscription expires. Kloudless will automatically refresh active Subscriptions that are close to expiring if possible.

  • last_cursor The most recent cursor for this Subscription. Can be used as the cursor when listing activity. This attribute will be left out when listing Subscriptions.

  • last_cursor_updated_at ISO 8601 timestamp of the most recent time last_cursor has been updated. This attribute will be left out when listing Subscriptions.

  • active Boolean indicating if the Subscription is active or not. Activity won’t be monitored for an inactive Subscription.

  • disable_reason Reason that the current Subscription is inactive.

  • default Boolean indicating if the Subscription is the default Subscription for this account. Setting a default Subscription helps access activity for this account without knowing the Subscription ID, by simply making a request to /subscriptions/default/activity instead. This is especially valuable when entire Kloudless applications are configured to automatically create subscriptions for all accounts connected to them. Defaults to false. Only one Subscription may be default for an account at any point in time.

  • monitored_resources Optional. A list of resource IDs indicating which resources are monitored by this Subscription. This field cannot be updated once written. To change it, delete and re-create the entire Subscription.

    The following services currently support this feature:

    • gdrive (non-admin only)
      • Configure up to four Shared Drives to monitor.
    • google_calendar, outlook_calendar
      • Configure up to five calendars to monitor.

    Kloudless will set sane defaults for this field if required and not provided. Here are the current list of defaults for each service:

    • gdrive (non-admin)
      • ["root"]
    • google_calendar, outlook_calendar
      • ["primary"]

    Refer to each Unified API’s docs for more information on reserved identifiers such as root for Storage and primary for Calendar.

  • monitored_resource_api Read-only. This field corresponds to the API category associated with the objects identified by monitored_resources.

  • monitored_resource_object_type Read-only. The object type of objects in monitored_resources.

  • subscription_type Possible values:

    • changes (default): This monitors any new activity in the account.
    • crawl: This performs an initial one-time retrieval of all file and folder metadata in the account, including across all users for admin accounts. All metadata found is published as new activity. This is currently limited to files and folders accessible via the Storage API. See crawl_type for where the metadata found is published.
    • sync (planned): Not yet implemented. This is similar to crawl but will copy files, folders, and objects found to a location in a configured account automatically.
  • crawl_type Only external is supported at the moment. Contact Kloudless to enable other values for your Subscriptions. Here are possible values:

    • external (default): The metadata found during the crawling is published to all configured webhooks, EventBridge receivers, and Google Cloud Pub/Sub topics.
  • created ISO 8601 timestamp indicating when the Subscription object was created.

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

  • type Always subscription.

  • api Always activity.

Note: If an upstream account is inaccessible for 90 days, or subscriptions for it are unable to be renewed for that time period, the Kloudless Subscription state will be removed along with related Activity data.

List Subscriptions 

list subscriptionsGET /accounts/{account_id}/subscriptions

List Subscriptions for an account.

The response contains the following information:

  • total Total number of objects.

  • count Number of objects in objects list.

  • objects List of Subscription objects.

  • type Always object_list.

  • api Always activity.

Example requests:

curl -L -H 'Authorization: Bearer [TOKEN]' \
    https://api.kloudless.com/v1/accounts/me/subscriptions
  • Response  200Toggle
  • Headers

    Content-Type: application/json

    Body

    {
        "total": 1,
        "count": 1,
        "objects": [
            {
              "id": 185,
              "account": 4,
              "type": "subscription",
              "api": "activity",
              "active": true,
              "disable_reason": "",
              "subscription_type": "changes",
              "default": false,
              "expiry": "2019-05-02T08:31:43.587905Z",
              "created": "2019-04-25T08:18:34.053393Z",
              "modified": "2019-04-25T08:31:58.742193Z",
              "monitored_resources": [
                "root"
              ],
              "monitored_resource_object_type": "folder",
              "monitored_resource_api": "storage",
              "last_cursor_updated_at": "2019-04-25T08:31:58.394494Z",
              "last_cursor": 2334,
            }
        ],
        "type": "object_list",
        "api": "activity"
    }

Create a Subscription 

create a subscriptionPOST /accounts/{account_id}/subscriptions

Create a Subscription for an account. Activity monitoring will begin once a Subscription has been created for a service. Currently, only one Subscription can be created per account.

Parameters:

  • active: Whether the Subscription is active.

  • subscription_type: Purpose of the Subscription; either changes or crawl. Please refer to the Subscription attributes above.

  • internal_state: The internal state of the Subscription being imported. Omit this parameter if you’re not importing a Kloudless Subscription.

  • monitored_resources: Optional. A list of resource IDs indicating which resources are monitored by this Subscription.

Example requests:

curl -H 'Authorization: Bearer [TOKEN]' \
    -H 'Content-Type: application/json' \
    -XPOST -d '{"active": true}' \
    'https://api.kloudless.com/v1/accounts/me/subscriptions/'

How to create a Subscription that monitors specific calendars

This example creates a Subscription that only monitors the primary calendar and a calendar with the ID fdGVzdEBrbG91ZGxlc3MuY29t.

curl -H 'Authorization: Bearer [TOKEN]' \
    -H 'Content-Type: application/json' \
    -XPOST -d '{
        "active": true,
        "monitored_resources": ["primary", "fdGVzdEBrbG91ZGxlc3MuY29t"]
    }' \
    'https://api.kloudless.com/v1/accounts/me/subscriptions/'
  • RequestToggle
  • Headers

    Authorization: Bearer [TOKEN]
    Content-Type: application/json

    Body

    {
      "active": true,
      "monitored_resources": [
        "primary",
        "fdGVzdEBrbG91ZGxlc3MuY29t"
      ]
    }
  • Response  201Toggle
  • Headers

    Content-Type: application/json

    Body

    {
        "id": 205,
        "account": 4,
        "type": "subscription",
        "api": "activity",
        "active": true,
        "disable_reason": "",
        "subscription_type": "changes",
        "default": true,
        "expiry": "2019-05-02T08:31:43.587905Z",
        "created": "2019-04-25T08:18:34.053393Z",
        "modified": "2019-04-25T08:31:58.742193Z",
        "last_cursor_updated_at": "2019-04-25T08:31:58.394494Z",
        "last_cursor": 2334,
        "monitored_resources": ["primary", "fdGVzdEBrbG91ZGxlc3MuY29t"]
        "monitored_resource_object_type": "calendar",
        "monitored_resource_api": "calendar"
    }

Retrieve a Subscription 

retrieve a subscriptionGET /accounts/{account_id}/subscriptions/{subscription_id}

Retrieve information about a Subscription with a Subscription ID for the current account.

Example requests:

curl -L -H 'Authorization: Bearer [TOKEN]' \
    https://api.kloudless.com/v1/accounts/me/subscriptions/185
  • Response  200Toggle
  • Headers

    Content-Type: application/json

    Body

    {
      "id": 185,
      "account": 4,
      "type": "subscription",
      "api": "activity",
      "active": true,
      "disable_reason": "",
      "subscription_type": "changes",
      "default": false,
      "expiry": "2019-05-02T08:31:43.587905Z",
      "created": "2019-04-25T08:18:34.053393Z",
      "modified": "2019-04-25T08:31:58.742193Z",
      "last_cursor_updated_at": "2019-04-25T08:31:58.394494Z",
      "last_cursor": 2334,
      "monitored_resources": [
        "root"
      ],
      "monitored_resource_object_type": "folder",
      "monitored_resource_api": "storage"
    }

Update a Subscription 

update a subscriptionPATCH /accounts/{account_id}/subscriptions/{subscription_id}

Update a Subscription for an account.

Parameters:

  • active: Whether the Subscription is active.

  • internal_state: The internal state of the Subscription being imported. Omit this parameter if you’re not importing a Kloudless Subscription.

Example requests:

curl -H 'Authorization: Bearer [TOKEN]' \
    -H 'Content-Type: application/json' \
    -XPATCH -d '{"active": false}' \
    'https://api.kloudless.com/v1/accounts/me/subscriptions/185'
  • RequestToggle
  • Headers

    Authorization: Bearer [TOKEN]
    Content-Type: application/json

    Body

    {
      "active": false
    }
  • Response  200Toggle
  • Headers

    Content-Type: application/json

    Body

    {
      "id": 185,
      "account": 4,
      "type": "subscription",
      "api": "activity",
      "active": false,
      "disable_reason": "deactivated_by_user",
      "subscription_type": "changes",
      "default": false,
      "expiry": "2019-05-02T08:31:43.587905Z",
      "created": "2019-04-25T08:18:34.053393Z",
      "modified": "2019-04-25T08:31:58.742193Z",
      "last_cursor_updated_at": "2019-04-25T08:31:58.394494Z",
      "last_cursor": 2334,
      "monitored_resources": [
        "root"
      ],
      "monitored_resource_object_type": "folder",
      "monitored_resource_api": "storage"
    }

Delete a Subscription 

delete a subscriptionDELETE /accounts/{account_id}/subscriptions/{subscription_id}

Delete a Subscription and all its related Activity.

Example request:

curl -L -H 'Authorization: Bearer [TOKEN]' \
    -XDELETE 'https://api.kloudless.com/v1/accounts/me/subscriptions/185'
  • Response  204

Webhooks 

Kloudless Webhooks are a way to be notified when new activity is available for one of the Accounts belonging to your Application.

Webhooks and similar notification mechanisms can be managed in the Activity Monitoring Configuration page. Kloudless supports three types of notification mechanisms:

Each are described in further detail below.

JSON Webhooks 

When a JSON Webhook is created, it will be tested by our servers to ensure that it works before saving it. In order for the test to “pass”, your application should respond with a 200 status code that includes just your Kloudless Application ID in the response body. The test webhook request is a POST with an empty JSON object ({}) in the request body.

Here is an example of a JSON Webhook notification from Kloudless:

POST / HTTP/1.1
Host: yourapp.example.com
Accept-Encoding: identity
Content-Length: 37
X-Kloudless-Signature: DojsMH34VH3sD+lB8sNBRwkbc7FXyCIRvEbijoCOz9I=
Content-Type: application/json
User-Agent: kloudless-webhook/2.0

{"account": 123, "subscription": 321}

The most important part of the POST request above is the body, which is a JSON object. The JSON object contains two fields:

  • account The ID of the account that triggered the activity.

  • subscription The subscription ID which triggered the webhook.

When your application receives a webhook, use the account and subscription IDs to list activity, along with a cursor if your application has one available from a prior response. The response to the endpoint above contains a cursor your application must store in its database.

Each time your application receives a webhook, include the latest cursor from your database in the query parameters while listing activity using the endpoint described above, and store the new cursor returned. This process guarantees your application will only receive new activity, in the order Kloudless became aware of them, regardless of the number of webhooks or whether they were all received.

Verifying JSON Webhooks

Kloudless includes a signature of the HTTP request that you can use to ensure that the request came from Kloudless and is untempered with. Here is how the signature is defined:

Base64Encode(HMAC-SHA256([API Key], [request contents]))

[request contents] in the example above would be the string {"account": 123, "subscription": 321}. For applications with multiple API Keys, the API Key used in the signature will be the oldest active one available.

NOTE: Even though there is a signature, you should accept webhook requests over HTTPS if possible. This ensures that data is not leaked to or tampered with by third-parties.

JSON Webhook Retries

If Kloudless doesn’t receive a HTTP response with a status code below 500 within 30 seconds (3.05 seconds for socket connection timeout and 27 seconds for read timeout), Kloudless assumes the webhook failed and attempts to retry it.

Kloudless retries webhooks with an exponential back-off. The initial time between retries is 1 second and the maximum time between retries can grow to 15 minutes. If the webhook continuously fails for 24 hours, Kloudless stops retrying until new activity is available after that time.

Amazon EventBridge Events 

Kloudless is an Amazon EventBridge Partner. This means that you can receive Kloudless Activity within your AWS environment using EventBridge, and then route the activity to AWS Lambda functions, Amazon EC2, SQS queues, or other valid EventBridge targets.

You can enable the Kloudless partner event source by searching for Kloudless within the Partner Event Sources list in your AWS EventBridge console.

Here is an example of an EventBridge event object:

{
    "detail-type": "eventbridge_webhook_notification",
    "source": "aws.partner/kloudless/your@email.com/api-id-123",
    "account": "111122223333",
    "time": "2017-12-22T18:43:48Z",
    "region": "us-west-1",
    "detail": {
        "account": 123,
        "subscription": 234,
        "activity": {
            "v1": [v1_activity_object],
            "v2": [v2_activity_object]
        }
    }
}

AWS wraps the Kloudless event payload within detail in an outer object that includes metadata about the EventBridge event. Here is a description of the fields Kloudless includes in the detail object:

  • account The ID of the account that triggered the activity.

  • subscription The subscription ID which triggered the webhook.

  • activity

    • v1 The activity data in Kloudless’ v1 API format. Please see here for details.
    • v2 The activity data in Kloudless’ v2 API format. Please see the Audit Activity section for details.

For more information on the top-level fields other than detail, please check AWS’ EventBridge Docs.

Filtering Events

AWS EventBridge Event Patterns can be used to filter EventBridge events.

For example, if you only want to receive activity where the Kloudless v2 event_category attribute is storage, you can use the following EventBridge pattern to filter for just that activity:

{
    "detail": {
        "activity": {
            "v2": {
                "event_category": ["storage"]
            }
        }
    }
}

Google Cloud Pub/Sub Messages 

You can configure Kloudless to publish Activity to a Google Cloud Pub/Sub topic as messages, and then consume those messages via a Google Cloud Pub/Sub subscription. Please refer to the Google Cloud Pub/Sub section on the Events configuration page of the Developer Portal for more information on how to set up Google Cloud Pub/Sub notifications.

Here is an example of a Pub/Sub message Kloudless could send:

{
    "account": 123,
    "subscription": 234,
    "activity": {
        "v1": [v1_activity_object],
        "v2": [v2_activity_object]
    }
}

The message data contains the following fields:

  • account The ID of the account that triggered the activity.

  • subscription The subscription ID which triggered the webhook.

  • activity

    • v1 The activity data in Kloudless’ v1 API format. Please see here for details.
    • v2 The activity data in Kloudless’ v2 API format. Please see the Audit Activity section for details.

Microsoft Azure Service Bus 

You can configure Kloudless to publish Activity to an Azure Service Bus topic as messages, and then consume those messages via an Azure Service Bus subscription. Please refer to the Microsoft Service Bus section on the Events configuration page of the Developer Portal for more information on how to set up Azure Service Bus notifications.

Here is an example of a Service Bus message Kloudless could send:

{
    "account": 123,
    "subscription": 234,
    "activity": {
        "v1": [v1_activity_object],
        "v2": [v2_activity_object]
    }
}

The message data contains the following fields:

  • account The ID of the account that triggered the activity.

  • subscription The subscription ID which triggered the webhook.

  • activity

    • v1 The activity data in Kloudless’ v1 API format. Please see here for details.
    • v2 The activity data in Kloudless’ v2 API format. Please see the Audit Activity section for details.

Session Topic

We support message sessions for ordering and grouping events based on the per-account subscription. Check Enable sessions in the Create Subscription page to enable session based subscription. After creating the subscription, you can receive messages with a specific SessionId which corresponds to the ID of the Activity Subscription).

If you are using Azure Functions, ensure that isSessionEnabled to True for the session subscription. Learn more from Azure Service Bus trigger for Azure Functions.

Topic filters and user-defined properties

You can also choose topic filters to filter messages by session id or our custom properties / the following fields:

  • SessionId system properties, corresponding to message field subscription.

  • accountId The ID of the account that triggered the activity.

  • v1ActivityType Any of the types described in Activity types.

  • v2EventCategory A classification of what the activity pertains to. Please see Activity Event Categories.

  • v2EventType A general action describing the activity. Please see Activity Event Types.

  • v2EventSubtype A more detailed description of the activity. Please see Activity Event Subtypes.