The Kloudless unified API connects end-user accounts via a single OAuth 2.0 authentication flow that developers can guide their users through. As a part of this, the Kloudless OAuth flow accepts scopes that indicate the level of access to request users for. Kloudless’ own OAuth flow requires scopes, but so do third-party OAuth flows that Kloudless proxies the request to. For example, Google’s APIs allow developers to redirect users to the Google consent page with a scope in the URI that indicates the data the app requires a user to grant access to.
Therefore, Kloudless allows developers to nest third-party API scopes within the Kloudless scope itself. This makes it much easier to customize an app’s level of access to any cloud service that Kloudless supports.
In this blog post, we’ll review how to request custom scopes with the Kloudless API.
The default flow
By default, Kloudless developers can set a scope such as
gdrive.storage to request the Kloudless unified API to immediately launch a specific app’s OAuth flow—in this case, Google Drive‘s. The default OAuth scope Kloudless uses during this process is
https://www.googleapis.com/auth/userinfo.email https://www.googleapis.com/auth/userinfo.profile https://www.googleapis.com/auth/activity https://www.googleapis.com/auth/drive.
Customizing the scopes Kloudless requests
Kloudless scopes have the form
<permission_identifier> part can be set to
"custom scope":raw to include a custom third-party scope during the authorization process. For example, we can alter the Google Drive scopes above by setting the
scope query parameter to
gdrive.storage."https://www.googleapis.com/auth/books":raw instead of
gdrive.storage. Here’s what the full URL to initiate the Kloudless OAuth flow looks like now, with the double quotes URL-encoded as
Here’s the consent screen Google now displays to the user:
Note that Kloudless also permits developers to add their own OAuth keys, as well as redirect to custom domains, to prevent the user from seeing “Kloudless” on the OAuth screen. This helps white-label the authentication process.
Kloudless also automatically adds any permissions absolutely required to the OAuth flow. For Google Drive, this includes
https://www.googleapis.com/auth/userinfo.email https://www.googleapis.com/auth/userinfo.profile https://www.googleapis.com/auth/activity. This ensures minimum functionality with the Kloudless API.
Special characters and multiple scopes
The custom scope format allows any characters within double quotes, aside from double quotes themselves. If a third-party scope absolutely requires double quotes, use a backslash to escape it. For example,
Kloudless also doesn’t differentiate between a single third-party scope and multiple. For example, use spaces to separate multiple Google Drive scopes within a single Kloudless scope:
. This mirrors Google Drive’s documentation on how to include multiple scopes in their OAuth flow.
Services like Zoho separate scopes with commas instead of spaces. This means the custom scope instead looks like
The Kloudless unified OAuth flow defaults to requesting users for read-write access. The custom scope format provides a mechanism for apps to customize this. This encourages best practices in data security, which call for only requesting the minimum amount of access an app requires. Check out our API Explorer to try out custom scopes for yourself!