Introduction to the Activity 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 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 v2 Activity API currently supports only a subset of services. For more information on services supported by our generally available Activity API, check out the v1 Docs. Information regarding Activity latency and retention can also be found in the v1 Docs.

The services that provide activity are listed below.

Audit Activity ¶

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

• box

• dropbox

• gdrive

  • Requires G Suite Enterprise.

• onedrivebiz

• sharepoint

• sharefile

• egnyte

By default, Kloudless projects have access to create, update, and delete activity for individual user accounts.

Contact us for access to the full suite of audit activity described below across all users in an organization via Kloudless admin accounts.

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.

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

Activity Object Fields ¶

Kloudless collects several types of activity data from each service and takes steps to unify the data formats seen into a single representation of activity in any connected account. To this end, Kloudless has classified data into multiple categories.

The following fields describe the type of activity received:

• event_category: A classification of what the activity pertains to. Please see Activity Event Categories below.

• event_type: A general action describing the activity. Please see Activity Event Types below.

• event_subtype: A more detailed description of the activity. Please see Activity Event Subtypes below.

The following fields describe information from Kloudless on the activity:

• id: Identifier of the Kloudless Activity.

• account: Account identifier of the connected Kloudless Service.

• timestamp: The time that the activity occurred at. Formatted in ISO 8601. null if unavailable.

• type: The type of object. Always activity.

• api: The API from which this object was retrieved from. Always activity.

• stream: The origin of activity data. Used to disambiguate when multiple overlapping sets of activity data are included. null if activity data is from a single source or can be de-duplicated by Kloudless. Currently only present for sharepoint and onedrivebiz.

• impersonate_for_target: The ID of the user to impersonate to access the target resource, where applicable.

• raw: Contains an object attribute with raw data.

The following fields describe unified information on the specific data of the activity:

• session: An object that describes the actor’s session.

  • type: login

• actor: An object with information describing the origin of the activity.

  • type: user or application.

• target: Data on the target resource of the activity.

  • type: file, folder, etc.

• metadata: Additional data provided on the activity details.

  • type: property, collaboration, etc.

Format ¶

{
    "id": <Activity ID>,
    "account": <Kloudless Account ID>,
    "api": "activity",
    "type": "activity",
    "event_category": "",
    "event_type": "<Action>",
    "event_subtype": "<Specific action>",
    "target": {
      ...,
      "api": "",
      "type": "<Target type>"
    },
    "previous_target": {<previous target metadata>}
    "impersonate_for_target": null,
    "timestamp": "<ISO 8601 timestamp>",
    "session": {
      "type": "login",
      "ip": "<IP address>",
      "user_agent": <string: User-Agent string>,
      ...,
    },
    "actor": {
        ...,
        "type": "<Actor type>",
        "api": "",
    },
    "metadata": [{
        "api": "",
        "type": "<Metadata type: one of several>"
    }],
    "raw": {
        "object": {
            ...,
        }
    }
}

The target, actor, and metadata objects refer to various types of Kloudless objects, depending on the activity received. In addition, these represnetaitons contain less information than the full Kloudless object, which may be returned in other Kloudless API endpoints. Please use the type field within the object to determine the type of object.

Activity Objects ¶

The objects returned by the Activity API may contain less information than the full Kloudless objects, which may be returned in other Kloudless API endpoints. You can use the id, type, and api attributes to retrieve their full metadata from other Kloudess API endpoints.

User ¶

Please refer to v1 User docs.

Group ¶

Please refer to v1 Group docs.

Domain ¶

• id: A unique identifier of the Kloudless Domain Object.

• name: The name of the domain.

• type: Always domain.

• api: Always team.

Collaboration ¶

• id: The unique identifier of this Collaboration object.

• resource: The resource object that this Collaboration object refers to.

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

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

• creator: The user that originally created this Collaboration object. May not be present if unavailable.

• links: A list of Service Link objects which can be used to link to the resource.

• permissions A list of Permission objects representing levels of access granted to other user, group, or domain.

• type Always collaboration.

Permission ¶

Please refer to Permission.

Link ¶

Please refer to Link.

Property ¶

• id: The unique identifier of this Property object.

• property_id: The underlying service property ID.

• template_id: The underlying service template/schema ID.

• key: User-defined string containing key value.

• key_type: String indicating type of data key value contains.

• values: Dictionary containing property values.

• target: The target role for the property. Can be either a user, group, or a domain.

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

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

• description: String with description for the Property Object.

• type: Always property.

• api: Always storage.

File ¶

Please refer to v1 File docs.

Folder ¶

Please refer to v1 Folder docs.

Email Message ¶

Please refer to v1 Email Message docs.

Email HyperLink ¶

A link in an Email that was clicked. Includes the following attributes:

• tag: The link’s HTML anchor tag.

• link: The link’s URL, parsed from tag.

• text: The link’s text, parsed from tag.

• type: Always hyperlink.

• api: Always email.

Login ¶

• ip: The IP address of the user.

• user_agent: The user-agent of the user.

• city: The city name from which the user logged in.

• region: The region from which the user logged in.

• country: The country from which the user logged in.

• device: The device information of the user used to log in.

• access_method: The access method used to log in.

• session_id: The session ID of the login session.

• host_name: The host name of the login session.

• type : Always login.

• api : Always events.

Activity Classification ¶

Event Categories ¶

category indicates the object or concept to which the activity primarily relates. The category for unknown activity will be unknown. Kloudless may add additional categories to describe activity as we continue to improve handling of unknown activity. Here are the currently available categories:

• authentication: Activity that relates primarily to instances of a user logging into or out of an account.

• calendar: Activity that relates primarily to Calendar API objects, such as calendars, calendar events, etc.

• collaboration: Activity that relates primarily to sharing, access policies, and roles.

• crm: Activity that relates primarily to CRM API objects, such as Account, Contact, Campaign, Lead, Opportunity and Task.

• email: Activity that relates primarily to Email API objects, such as email Message.

• messaging: Activity that relates primarily to Chat API objects, such as chat Message and Conversation.

• object: Activity that relates primarily to generic objects

• storage: Activity that relates primarily to file-like or folder-like objects.

• team: Activity that relates primarily to Team API objects, such as Users and Groups.

• unknown: Activity that Kloudless has not yet unified.

Event Types ¶

type refers to a general action describing the activity. The type value will be one of the following:

• add: A resource was created.

• access: A resource was accessed.

• update: A resource was updated.

• delete: A resource was deleted.

• error: An error occurred with a resource.

• unknown: An unknown activity occurred with a resource.

Event Subtypes ¶

subtype provides any available specificity about the objects and information involved in the activity and/or the actions or occurrences that generated it. The subtypes for each event_category may be duplicated, but mean the same and are located below:

authentication ¶

• login: a user logged in to a cloud service.

• logout: a user logged out of a cloud service.

calendar ¶

• rename: a resource was renamed.

• add_attendee: an attendee was added to an event.

• update_attendee: an attendee status was updated.

• remove_attendee: an attendee was removed from an event.

• event_update_time: an event’s time was updated.

collaboration ¶

• permission_create: a new permission was added for a resource.

• permission_update: an existing permission was updated for a resource.

• permission_delete: an existing permission was deleted for a resource.

• permission_update_expiration: an existing permission’s expiration was updated for a resource.

• permission_access_scope: the default access scope for a resource was updated.

• permission_visibility: the default visibility of a resource was updated.

• permission_invite: a pending permission was added for a resource.

• permission_accept: a pending permission was accepted for a resource.

• permission_reject: a pending permission was rejected for a resource.

• permission_request: requested pending permission for a resource.

• link_create: a shared link was created for a resource.

• link_update: a shared link was modified for a resource.

• link_delete: a shared link was removed for a resource.

• link_update_expiration: a shared link’s expiration was updated for a resource.

• link_update_password: a shared link’s password was updated for a resource.

• property_update: a metadata/property value was updated for a resource.

storage ¶

• copy: a resource was created via copy.

• download: a resource was downloaded.

• move: a resource was moved.

• parent_update: a resource was added to a new location.

• preview: a resource was viewed.

• print: a resource was printed.

• rename: a resource was renamed.

• revert: a resource was reverted to a previous version.

• tag_create: a tag was created for a resource.

• untrash: a resource was created via undelete/untrash.

• comment_create: a comment was created for a resource.

• comment_update: a comment was updated for a resource.

• comment_delete: a comment was deleted for a resource.

• property_create: a metadata/property value was created for a resource.

• property_update: a metadata/property value was updated for a resource.

• property_delete: a metadata/property value was deleted for a resource

email ¶

• email_open: an email message sent via the Kloudless Email API was opened.

• email_click: an email link in a message sent via the Kloudless Email API was clicked.

team ¶

• add_user: a user was added to a group.

• approve_user: a user was approved to join a group.

• invite_user: a user was invited to join a group.

• remove_user: a user was removed from a group.

• rename: a resource was renamed.

• revoke_user: a user’s invitation to join a group was revoked.

• team_approve: a user was approved to join an organization.

• team_reject: a user was rejected from joining an organization.

• team_invite: a user was invited to join an organization.

• team_request: a user requested to join an organization.

• user_accept: a user accepted the invite to join a group.

• user_reject: a user rejected the invite to join a group.

• user_bulk_create: users were added to an organization in bulk.

• password_update: a user’s password was updated.

• download: a resource was downloaded.

• move: a resource was moved.

• untrash: a resource was created via undelete/untrash.

unknown ¶

• unknown: an unknown subtype. The raw data contains further information.

Activity Endpoints ¶

List Activity 

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

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 Monitored Resources 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.
  • gmail, outlook_email, exchange_email
    • See the Email Activity section.
  • sharepoint
    • Configure up to four Document Libraries to monitor. If the specified ID is a SharePoint site, the default Document Library of the site will be monitored. If the specified resource is a folder, the corresponding Document Library will be monitored instead.
    • For admin accounts, if no monitored_resources is set, all Document Libraries across the entire account will be monitored by default.
  • onedrivebiz (admin only)
    • Configure up to four Document Libraries to monitor.
    • For non-admin accounts, monitored_resources is not supported. Instead, the root drive of the account will always be monitored by default.
  • salesforce
    • Configure up to 40 object names to monitor. Include *__c to monitor all the custom objects. E.g. ["account", "contact", "ContentDocument", "CustomObject__c", "*__c"]. Due to the 40 PushTopics limit, we prioritize specified objects over the ones we matched for “*__c”.
  • slack (non-admin only)
    • Configure up to 5 conversations to monitor.
  • Any services that support the crawl Subscription type. Check subscription_type below for more details.

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

  • gdrive (non-admin)
    • root
  • google_calendar, outlook_calendar
    • primary
  • salesforce
    • ContentDocument
    • ContentWorkspace
    • Document
    • Attachment
    • FeedItem
    • FeedComment
    • FeedAttachment
    • account
    • contact
    • campaign
    • opportunity
    • lead
    • task

  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. All services that support the Storage API support the crawl subscription type, other than Email services. See crawl_type for where the metadata found is published.
  • analytics: Activity related to analytics. Currently only used to publish open and click activity on messages sent via the Email API.
  • 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.

Monitored Resource ¶

Monitored Resources are sub-objects configured within a Subscription object that specify the resources to track activity for, crawl, or otherwise perform the Subscription’s intended action on. A Monitored Resource has the following attributes:

• resource: The resource’s ID, reserved identifiers, or object name.

• user: Optional. For Kloudless accounts with multiple users, such as org-wide admin accounts, this specifies the ID of the user through which the resource can be accessed.

List Subscriptions 

curl -L -H 'Authorization: Bearer [TOKEN]' \
    https://api.kloudless.com/v2/accounts/me/subscriptions

Create a Subscription 

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

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

Retrieve a Subscription 

curl -L -H 'Authorization: Bearer [TOKEN]' \
    https://api.kloudless.com/v2/accounts/me/subscriptions/185

Update a Subscription 

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

Delete a Subscription 

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

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:

• JSON Webhooks

• Amazon EventBridge Events

• Google Cloud Pub/Sub Messages

• Microsoft Azure Service Bus

Each is 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]
        }
    }
}

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. See the v1 Activity object attributes 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 v1 type attribute is add, you can use the following EventBridge pattern to filter for just that activity:

{
    "detail": {
        "activity": {
            "v1": {
                "type": ["add"]
            }
        }
    }
}

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]
    }
}

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. See the v1 Activity object attributes 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]
    }
}

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. See the v1 Activity object attributes 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.