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.

Customizing the scopes Kloudless requests

Kloudless scopes have the form <service_identifier>.<api_identifier>.<permission_identifier>. The <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 %22:

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

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, "custom \"scope\"":raw.

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!