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.
scope is a space-delimited string of Kloudless OAuth scopes. In this KB
article, we describe the format of this string.
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
Here is a list of available Kloudless API categories:
|Scope||Kloudless API Category|
|helpdesk||Help Desk (beta)|
Specify scopes for multiple API categories at once by separating them with
# Specifying individual services
To only display specific services, include the list of service identifiers
delimited with spaces. Refer to our
for a list of all supported services and their respective service identifiers.
For example, setting the
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
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
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,
gdriveis the same as
gdrive:normal, as are
: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:
- Configuring custom OAuth Keys with appropriate scopes.
- 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_identifieris the identifier of the service to use the scope for
[:admin]is entirely optional, as described in the previous section
"<custom_scope>":rawincludes the custom upstream scope to use within double quotes, with the suffix
:rawdenoting 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 \" files\"":raw(hypothetical example)
Real-world examples for specific services:
# 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
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
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:
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
identifier along with it's modifier (
normalas described earlier). Defaults to
- The API Segment: Defaults to
all, but can be altered to narrow which specific APIs to access, such as any category-specific API (
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
allin 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.storagewon't have access to the Activity Monitoring API as
gdrive.eventswouldn't be present in the Account's
- 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.