Kloudless API Guide

# Scopes

The scope parameter in the Kloudless OAuth flow describes the services that a user is prompted to connect to your app, as well as specific levels of access to request the user to grant to your app.

The scope is a space-delimited string of Kloudless OAuth scopes. In this KB article, we describe the format of this string.

# Default: any

The default OAuth scope in the Kloudless OAuth flow is any, which represents any service enabled for the Kloudless application. This displays all services to a user to connect via the non-admin authentication flow that grants an application access to that specific user's data.

# Specifying API Categories

Some apps may need to prompt a user to connect any cloud storage service, or any calendar account, of their choice. To do so, include the category identifier in the scope string. For example, the scope could be storage.

Here is a list of available Kloudless API categories:

Scope Kloudless API Category
storage Cloud Storage
calendar Calendar
email Email
crm CRM
messaging Messaging
itsm ITSM
helpdesk Help Desk (beta)

Specify scopes for multiple API categories at once by separating them with spaces, e.g., storage calendar.

# Specifying individual services

To only display specific services, include the list of service identifiers delimited with spaces. Refer to our documentation for a list of all supported services and their respective service identifiers. For example, setting the scope to box dropbox will prompt users to choose between connecting a Box account or a Dropbox one.

If the scope resolves to a single service, Kloudless will automatically redirect the user to that service's authentication page, rather than displaying a list of services to connect. For example, setting the scope to gdrive will immediately redirect the user to the Google login page as part of the Google Drive OAuth flow.

# Connecting Admin Accounts

With the default scope format, users can only connect accounts to your app that do not require admin privileges for org-wide or tenant-wide access to data. Some Kloudless API features like the Team API and User Impersonation require admin users to instead proceed through the OAuth flow and grant access to all data in the cloud service, including all users' individual data.

Kloudless differentiates authenticating these "admin accounts" from non-admin account authentication by suffixing the special modifier string :admin to any of the service or category identifiers mentioned above.

There are three modifier strings that toggle which types of services a user is prompted to connect:

  • :admin: Displays services that have a special admin authentication flow, or support connecting admin accounts for access to additional features and API endpoints.
  • :normal: Intended to authenticate individual user accounts. This is the default if none is provided. For example, gdrive is the same as gdrive:normal, as are calendar and calendar:normal.
  • :all: Displays options to authenticate services using both non-admin and admin authentication flows, where supported for each.

Here are some examples:

  • any:admin: Displays all services that support admin authentication.
  • storage:admin: The same as above, but restricted to just Storage services.
  • box:admin: The same as above, but restriced to just Box. Grants access to the Box audit log, user and group membership information, and all user data in the account's Box organization.
  • any:all: Displays all supported services.

# Customizing Requested Permissions

Upstream services' OAuth flows often support scopes of their own to control the level of access to prompt a user to grant to an app. Kloudless supports customizing these scopes to limit the level of access users are requested to grant.

There are two approaches discussed below to customize the upstream scopes requested:

  1. Configuring custom OAuth Keys with appropriate scopes.
  2. Including the required scopes in the Kloudless OAuth flow.

Warning: Custom scopes will overwrite Kloudless' preset scopes. If an account has insufficient permissions granted via the scopes used during authentication, API requests to it will fail with a "permission denied" or similar error. In addition, custom scopes are not available for services that do not authenticate users over OAuth at all, such as Amazon S3 or SFTP.

# Configuring Custom OAuth Keys

Configuring Custom OAuth Keys is always recommended where supported. Benefits include custom branding during the OAuth flow, dedicated rate-limits, and ownership of users' tokens. One other benefit of custom OAuth Keys is that a developer can customize the scopes requested.

Several applications, such as Box, Salesforce, and OneDrive, allow developers to configure the default scopes requested when setting up the developer app and retrieving a unique Client ID and Secret (the "Custom OAuth Keys"). When the Client ID and Secret are configured on the Kloudless Developer Portal's Custom OAuth Keys page, Kloudless will prompt the user for those scopes rather than the default that Kloudless uses.

Some applications such as Google Drive, Google Calendar, and Gmail require the OAuth scopes to be included within the OAuth flow itself. In this case, the "Custom raw scopes" field in the OAuth Credential configuration form can be used to specify the upstream scopes Kloudless should include when launching that service's OAuth flow. Alternatively, the scopes can be included during the OAuth flow as described below.

# Specifying Upstream Scopes during OAuth

Where supported or required by the upstream service, Kloudless' own OAuth flow supports embedding upstream scopes within the Kloudless scope string to instruct Kloudless to use that specific scope when redirecting the user to the upstream service's OAuth flow.

The general form of each Kloudless scope that includes a custom scope is:

<service_identifier>[:admin].all."<custom_scope>":raw

where:

  • service_identifier is the identifier of the service to use the scope for
  • [:admin] is entirely optional, as described in the previous section
  • "<custom_scope>":raw includes the custom upstream scope to use within double quotes, with the suffix :raw denoting it isn't a Kloudless permission identifier. In the rare event that the upstream scope itself requires double quotation marks, they can be escapted by using a backslash (\) character prior to each double quote.
  • .all. is the "API segment". This can be ignored for the purposes of this section. Feel free to refer to the appendix at the end of this guide for more information on the scope string format.

Here are some examples:

  • hubspot.all."contacts":raw
  • hubspot.all."contacts files":raw
  • hubspot.all."contacts \" files\"":raw (hypothetical example)

Real-world examples for specific services:

  • hubspot.all."contacts files":raw
  • gdrive.all."https://www.googleapis.com/auth/userinfo.email https://www.googleapis.com/auth/drive.readonly":raw
  • google_calendar.all."https://www.googleapis.com/auth/calendar.readonly https://www.googleapis.com/auth/calendar.settings.readonly":raw

# More Examples

  • box dropbox gdrive:all: Allow users to connect either Box, Dropbox, or Google Drive accounts. Both normal and admin authentication flows are displayed for Google Drive.
  • gdrive:all dropbox:admin box: Display options to connect a non-admin or admin Google Drive account, an admin Dropbox account, or a non-admin Box account.

# Scopes in the Kloudless Accounts API

The Kloudless Account object's effective_scope attribute indicates the maximum level of access available through the Account. Please refer to the Account docs for more details.

# Appendix: Scope Format

The most common uses of the scope string are detailed above. This section describes the format of the scope string for advanced usage that requires customizing the scope further.

As mentioned previously, a valid scope string is a space-delimited string of individual scopes. If present in the OAuth flow, it indicates which services a user may connect and permissions to request. If present via the API, it indicates that indicate the level of access available through an account, or through the Kloudless subscription plan.

The general form of each individual scope string is:

<service_identifier>[:service_modifier][.<api>[."<custom_scope>":raw]]

where any string inside brackets is optional.

As seen above, each individual scope string consists of three segments, separated with period characters (.):

  • The Service Segment: The first sub-string that includes the service or category identifier along with it's modifier (:all, :admin, or normal as described earlier). Defaults to any.
  • The API Segment: Defaults to all, but can be altered to narrow which specific APIs to access, such as any category-specific API (storage, calendar, crm, etc.) or the following feature-specific APIs:
    • sharing: The v2+ Sharing API
    • team: The Team API
    • contact: The Calendar API's Contacts endpoints
    • events: The Activity Monitoring API
    • meta: The Meta API (only valid for Kloudless developer accounts) In general, always use all in this segment, since it automatically applies all available APIs supported by the service. Specifying only individual APIs might cause unexpected behavior. For instance, a Google Drive account connected with gdrive.storage won't have access to the Activity Monitoring API as gdrive.events wouldn't be present in the Account's effective_scope.
  • The Permission Segment: Represents specific scopes or permissions to request when prompting the user for access to their account. The preceding API Segment is required for this segment to exist See the section above on customizing requested permissions for more details.

← Admin Accounts and Impersonation →