Back to top

Introduction to the Events 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 Events API endpoints listed below.

Overview

Kloudless monitors accounts using a variety of service-specific implementations to be aware of activity occurring within each account.

The v2 Events API currently supports only a subset of services. For more information on services supported by our generally available Events API, check out the v1 docs. Event latency information can also be found there.

The services included are listed below by API category.

Audit Events

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

  • box

  • dropbox

  • gdrive

    • Requires G Suite Enterprise.
  • onedrivebiz

  • sharepoint


Events 

Overview

Actions such as creating, modifying, or deleting resources generate events that we track. These are represented as a stream of event objects.

To enable access to event data for accounts connected to your application, visit the App Details page and ensure the checkbox for ‘Collect Events’ is checked.

Up to 10,000 events over the previous 24 hours are stored temporarily in Kloudless’s database for efficient retrieval by your application.

Event Object Fields

Kloudless collects several types of event 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 event received:

  • event_category: A classification of what the event pertains to.

  • event_type: A general action describing the event.

  • event_subtype: A more detailed description of the event (please see Event subtypes below).

The following fields describe information from Kloudless on the event:

  • id: Identifier of the Kloudless Event.

  • account: Account identifier of the connected Kloudless Service.

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

  • type: The type of object. Always event.

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

  • stream: The origin of event data. Used to disambiguate when multiple overlapping sets of event data are included. null if event 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 event:

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

    • type: login
  • actor: An object with information describing the origin of the event.

    • type: user or application.
  • target: Data on the target resource of the event.

    • type: file, folder, etc.
  • metadata: Additional data provided on the event details.

    • type: property, collaboration, etc.

Format

{
    'id': ,
    'account': ,
    'api': 'events',
    'type': 'event',
    'event_category': '',
    'event_type': '',
    'event_subtype': '',
    'target': {
      ...,
      'api': '',
      'type': ''
    },
    'previous_target': {}
    'impersonate_for_target': null,
    'timestamp': '',
    'session': {
      'type': 'login',
      'ip': '',
      'user_agent': ,
      ...,
    },
    'actor': {
        ...,
        'type': '',
        'api': '',
    },
    'metadata': [{
        'api': '',
        'type': ''
    }],
    'raw': {
        'object': {
            ...,
        }
    }
}

The target, actor, and metadata objects refer to various types of Kloudless objects, depending on the event 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.

Event Objects

The objects returned by Event API may contain less information than the full Kloudless objects, which may be returned in other Kloudless API endpoints. You may identify them with the id, type and api in other Kloudess APIs.

User

Please refer to v1 User docs.

Group

Please refer to v1 Group docs.

Domain

  • id: An 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.

  • id: The ID of the service link.

  • resource_id: The ID of the resource the link refers to.

  • type: Always service_link.

  • api: Always sharing.

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

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

  • creator: The user or group object that originally created this link.

  • url: The URL of the link.

  • download_url: The download URL of the link.

  • expiration: Expiration timestamp of the link in the ISO 8601 format.

  • password: A boolean indicating if the link is password-protected.

  • targets: A list of user or group objects that have access to the link.

  • capabilities: The capabilities the targets each have. Please refer to Sharing API capabilities for more information.

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: TBD

  • key_type: TBD

  • values: TBD

  • api: TBD

  • targets: TBD

  • 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: TBD

  • type: Always property.

File

Please refer to v1 File docs.

Folder

Please refer to v1 Folder docs.

Login

TBD

Event Classification

Event Categories

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

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

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

  • collaboration: Events that relate primarily to sharing, access policies, and roles.

  • object: Events that relate primarily to generic objects

  • storage: Events that relate primarily to file-like or folder-like objects.

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

  • unknown: Events that Kloudless has not unified.

Event Types

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

  • create: 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 event occurred with a resource

Event Subtypes

subtype provides any available specificity about the objects and information involved in the event 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_guest: a guest was added to an event

  • remove_guest: a guest was removed from an event

  • event_update_time: an event’s time was updated

collaboration

  • 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_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

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

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

unknown

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

Events Endpoints

List Events 

list eventsGET /accounts/{account_id}/events{?cursor,page_size,from,until}

Events are retrieved using this endpoint. They are returned as a list of event objects in the order that our system was made aware of them. There is a small chance that there will be duplicate events in the stream, but the net result of applying all of these events will reflect the current state of the underlying storage service. Kloudless takes steps to minimize duplicate events where possible.

The response contains the following fields:

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

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

  • count: Number of events returned.

  • type: Will always be object_list.

  • api: Will always be events.

The returned cursor should be used in subsequent requests so that only events that have not been seen previously are returned.

Example Request:

curl -H 'Authorization: Bearer [TOKEN]' \
    'https://api.kloudless.com/v2/accounts/123/events?cursor=121'

Time-Based Event Retrieval

The parameters from and until retrieve events 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)

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 events is returned, there are no events within the time range specified or after the cursor.

  • Parameters
  • cursor
    string (optional) 

    The last cursor in the event stream that your application has seen. The cursor can also be set to after-auth, which will retrieve events that have occurred after the account was connected. This is useful if prior events are 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.

    In addition, the latest upstream_cursor can be provided as a cursor to retrieve any events after that point in the event stream.

    page_size
    number (optional) Default: 1000 

    Number of events 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
    string (optional) 

    An ISO-8601 string specifying the time of the oldest event in the range to return (inclusive). Can be used without until.

    until
    string (optional) 

    An ISO-8601 string specifying the latest time prior to which to return events (exclusive). Must be used along with from. Non-overlapping queries can be performed since the event 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": "events",
    }

Retrieve Latest Cursor 

Retrieve Latest CursorGET /accounts/{account_id}/events/latest

This returns the latest cursor that is available. This makes it easier to start fetching new events immediately, rather than making a potentially large initial request.

This returns an object with the following fields:

  • cursor: The most recent cursor for this account

  • upstream_cursor: Cursor from the upstream service. This indicates that the upstream event stream can be directly queried.

Either cursor can be used in the cursor parameter when retrieving events.

Example Request:

curl -H 'Authorization: Bearer [TOKEN]' \
    'https://api.kloudless.com/v2/accounts/123/events/latest'
  • Response  200Toggle
  • Headers
    Content-Type: application/json
    Body
    {
      "cursor": "29",
      "upstream_cursor": "1veNDdHe2_99qcndJ6cId",
      "type": "cursor",
      "api": "events"
    }

WebHooks 

WebHooks are a way to become notified when new events become available for one of the accounts belonging to your application. Webhooks can be created in the Application Details section of the developer portal. When the 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 OK status and have just your application ID in the response body. The test webhook request is a POST with an empty request body.

Here is an example standard webhooks requests:

POST / HTTP/1.1 Host: yourapp.example.com Accept-Encoding: identity Content-Length: 14 X-Kloudless-Signature: DojsMH34VH3sD+lB8sNBRwkbc7FXyCIRvEbijoCOz9I= Content-Type: application/x-www-form-urlencoded User-Agent: kloudless-webhook/1.0

account=593652

The most important part of the POST request above is the body, which is a normal HTTP form. The body of the form contains a single field, account, the value of which is the ID of the account that triggered the event. There will only be one account in each webhook request.

We provide a signature of the request that you can use to ensure that the request came from us and is untampered 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=593652. 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.