Introduction 

v2 improves Kloudless’s support for new APIs, features as well as authentication mechanisms.

This migration guide provides an overview of backwards incompatibilities that require changes to be made to your application when migrating from v1 to v2.

Here is a summary of the backwards-incompatible changes described below:

• raw_id has been moved to the raw object’s id attribute.

• Meta tokens have replaced Developer Keys.

• Some Account properties have been renamed.

• Subscription-based activity monitoring via the new Activity API deprecates the Events API.

  • The Event objects in the Events API are now Activity objects.

• The format and value of cursor changes in the Activity API.

• cursor format and value changes in Activity API.

• Folder structure changes in the following services:

  • Dropbox

• New Calendar Event format:

  • Deprecate reminder in favor of reminders and use_default_reminder.

• Raw CRM data not returned by default.

• Raw type not included in the CRM Schema raw response data.

• Webhooks now contain JSON payloads.

• Use Client Secrets instead of API Keys during OAuth.

• Changes to the asynchronous Task object’s state metadata.

• Generic CRM Object CRUD API and Schema API endpoints have migrated to the Object API.

• The data type for monitored_resources changes from a list of strings to a list of objects.

New location for Raw IDs 

Previously, file metadata and other objects would include the raw_id attribute. This has been moved to the raw object’s id attribute instead.

For example, here is the format in v1:

{
        "raw_id": "ABCDEF-123"
        "raw": {
            "object": { ... raw data ... },
        }
    }

Here is the equivalent format in v2:

{
        "raw": {
            "id": "ABCDEF-123",
            "object": { ... raw data ... }
        }
    }

Developer Keys replaced with Meta tokens 

Meta tokens (OAuth 2.0 Bearer Tokens) have replaced Developer Keys. Meta tokens are automatically created when a user signs up and are used to authorize access to your Kloudless developer account and information associated with it.

Authorization: Bearer {token: string}

__NOTE__: DeveloperKey authorization available in v1 has been deprecated in
favor of Meta Bearer tokens. All existing Developer Keys have been transitioned
to Meta Bearer tokens and can be used with the "Bearer" Authorization scheme
immediately.

All existing DeveloperKey keys have automatically been transitioned to Bearer tokens and will work with the Bearer Authorization type.

Some Account properties have been renamed. 

The attributes below have been renamed to avoid confusion, but their values remain the same:

• active is now known as enabled

• deactivation_code is now known as disable_reason

Events API -> Activity API 

The Events API has been deprecated and is now known as the Activity API, with support for Subscription objects. This change has been implemented in part to help avoid further confusion with the Calendar Events API.

Event objects have been renamed to Activity objects.

Here are some of the major updates to be aware of:

• The cursor returned is always returned as a string and should not be treated as an integer as it can vary. If there is no cursor since no activity has been collected yet, the cursor will be null instead of -1 or 0 as before.

• The /events/latest endpoint is no longer necessary since the Subscription object contains the data it used to provide.

• The monitor_team_drivesand monitor_calendars attributes originally set via the Accounts API are now replaced with the monitored_resources attribute on newly created Subscription objects.

The older Events API endpoints are listed below for reference, with some details on the changes above.

List Events 

Retrieve Latest Cursor 

curl -H 'Authorization: Bearer [TOKEN]' \
    'https://api.kloudless.com/v1/accounts/123/events/latest'

Audit Activity 

The new Activity format provides more detailed information on activity in connected accounts. This includes unified data on the action/cause of an activity, metadata associated with said action, as well as the action’s target.

Several new unified activity categories and types have been introduced. Check out the v2 Activity API here.

In addition to new attributes that provide more granular and accurate activity data, the remaining attribute is no longer present due to limitations with accuracy and performance.

The older Activity format has been maintained below for reference.

v1 Audit Activity Types and Format ¶

While most audit data is presented as received via the Kloudless Activity’s raw attribute, Kloudless maps recognized activity to known event types and formats. Here are the possible activity types Kloudless provides:

• unknown: This is the default activity event type for an activity that is not mapped to a Kloudless Audit Activity event type specified in this list. The raw data for the activity object will provide access to the original activity received from the third-party service for further analysis.

• login: A user successfully logged into the account.

• login_failed: A user failed to log into the account.

• logout: A user successfully logged out of the account.

• share_link: A link to a resource was shared.

• unshare_link: A shared link to a resource was removed.

• share_update: A shared link to a resource was modified.

• collaboration_add: A collaborator was added to a resource.

• collaboration_invite: A collaborator was invited to a resource.

• collaboration_accept: A collaborator has accepted the invite to a resource.

• collaboration_delete: A collaborator was removed from a resource.

• collaboration_update: The resource’s collaborators were updated.

• view: The resource was viewed.

• download: The resource was downloaded.

• user_invite: A user has been invited.

• user_add: A new user was created.

• user_delete: A user was deleted.

• user_update: A user was updated.

• group_add: A new group was created.

• group_delete: A group was deleted.

• group_update: A group was updated.

• group_add_user: A user was added to a group.

• group_delete_user: A user was removed from a group.

Audit Activity objects may also have the fields below in lieu of metadata and previous_metadata. They may either not be present or default to {} where unavailable or not applicable.

• user: Information on the user associated with the activity. e.g.: The user that was created, or the user a resource was shared with.

• previous_user: The previous user data that was modified.

• group: Information on the group associated with the activity.

• previous_group: The previous group data that was modified.

• link: Metadata on a shared link. Includes the link’s URL.

• login: Metadata on a login or attempted login.

• collaboration: Metadata on a collaboration.

See the Team endpoints for more information on user and group objects.

Folder Structure Changes 

A few changes have been made regarding the folder structure in the services below.

Dropbox ¶

Folder creation and file uploads with parent_id set to root will now create/upload the resource under under the shared root folder for the Dropbox Business Organization instead of the private Home folder of the connected account. The root folder of the Dropbox Business Organization is the folder shown in the Files tab in the left-hand side navigation menu of the Dropbox Web UI.

Files and folders in the root folder can be accessed by the team, and are not private like data in the Home folder. Please ensure that all new folders created and files uplaoded to the root folder are intended to be shared.

Calendar Event format changes 

The attribute reminder has been replaced by reminders, which provides more information such as the reminder name and mechanism.

The new attribute use_default_reminder has been added to indicate whether to use the default reminder or not. Only supported for google_calendar.

For example, here is the format in v1:

{
    "reminder": 30
}

Here is the format in v2:

{
    "use_default_reminder": false,
    "reminders": [{
        "minutes": 30,
        "message": "popup"
    }]
}

See the Calendar Event Docs for more information on reminders and use_default_reminder.

Raw CRM data not returned by default 

All CRM API endpoints now only return raw upstream data if the X-Kloudless-Raw-Data: true header was included in the API request. This is consistent with the behavior of other API endpoints. Previously, some CRM accounts defaulted to returning raw upstream data along with the unified response. This was the case with developers using Kloudless prior to 2019 with Salesforce, Dynamics, Oracle, and Pipeliner.

Raw type not included in the CRM Schema response 

Use the new service_object_name and service_field_name attributes to determine the raw object and field names respectively in the Object Schema response, rather than checking the raw data for this information. The raw data continues to include the schema data provided by the upstream service, but this is not the same type as the actual object it is describing, so the raw->type attribute is excluded in v2 onwards for consistency.

Webhooks available with JSON payloads 

Previously, Kloudless sent webhooks to your server with a URL-encoded body data. However, a JSON payload is more extensible and enables Kloudless to include additional information about the new activity available. Kloudless therefore introduced webhooks that transmit JSON payloads. The v2 API and above require using this new format.

Here are two ways to migrate legacy webhooks to new webhooks that include JSON data:

1. Update your existing webhook endpoints to accept both content types (application/x-www-form-urlencoded and application/json). Then click the “Migrate” button on the “Legacy Webhooks” section of the Activity Monitoring Configuration page for each of your Kloudless apps.

2. Add new webhooks to each of your apps’ Activity Monitoring Configuration pages. This will create new webhooks that receive JSON payloads instead. After you confirm your servers successfully process this JSON data, click the “Delete All” button in the “Legacy Webhooks” section to delete all legacy webhooks.

See the Webhooks API reference for more information.

Use Client Secrets instead of API Keys during OAuth 

API Keys cannot be used as Client Secrets in the OAuth authorization code grant flow after April 1, 2021. The App Details page of the developer portal provides the option to create Client Secrets for this purpose instead. Client Secrets offer security benefits over API Keys as they do not provide access to all existing accounts’ data via the API, unlike API Keys.

All API Keys created prior to April 1, 2021 can still be used as the Client Secret in the OAuth flow in versions prior to v2, but not in v2 after that date.

Changes to the asynchronous Task object's state metadata 

The state attribute is now known as status. The status attribute is already present in v1 for developers to migrate seamlessly. New developers may already be using this attribute.

The value of status differs from the deprecated state attribute in the following ways:

• PENDING is now known as UNKNOWN.

• RECEIVED is removed. All received tasks will be marked as STARTED.

For example, here is the format with the older attributes:

{
  "id": "8e3938f9-dde7-4a57-b9a2-7ad282461073",
  "state': "PENDING",
  "info": null
}

Here is the equivalent format in v2 with the newer attributes:

{
  "id": "8e3938f9-dde7-4a57-b9a2-7ad282461073",
  "status": "UNKNOWN",
  "info": null
}

CRM Objects and Schemas -> Object API endpoints 

As Kloudless expands connectors, the CRM API’s generic Object CRUD API and Schema API endpoints are valuable in other Unified APIs as well. Therefore, these endpoints have moved from within the /crm/ namespace to the new /object/ namespace instead:

• The /crm/objects?raw_type={service_object_name} CRUD API endpoints are now available at /object/raw/{service_object_name} instead, in the Generic Object CRUD API.

  • The raw ID may be encoded now, instead of un-encoded, but the API behavior is otherwise identical.

• The /crm/schemas list and retrieval API endpoints are now available at /object/schemas instead, in the Schema API.

Monitored Resources Changes 

A Subscription object’s monitored_resources is now a list of “Monitored Resource” objects rather than a list of resource identifier strings.

This lets us associate additional attributes with each resource to monitor, such as the ID of the user to impersonate to access that resource.