Introduction to Kloudless OAuth 2.0 

Kloudless uses OAuth 2.0 to authenticate users, and provides your application with an access token to use to perform API requests to that user’s account.

In addition, your application’s confidential API Key can be used to access data for any account connected to your application.

Custom OAuth credentials 

By default, users are authenticated with a set of OAuth keys for the appropriate cloud service owned by Kloudless. This means that they will see that ‘Kloudless Platform’ is requesting access to their account on Dropbox, Box, etc.

We recommend configuring your own OAuth keys for the cloud services you’d like to support. Custom OAuth keys allow you to white label you app’s authentication process. You can configure these keys on the developer portal’s Custom OAuth Keys page.

Authorizing API requests 

Prior to detailing how to authenticate users, we will demonstrate how to authorize API requests once user accounts have been connected.

A developer can use an Authorization header to authorize requests for the Kloudless API. Kloudless offers two options for an Authorization header: Bearer for OAuth tokens, or APIKey for application-wide access.

OAuth 2.0 Bearer Token Authorization 

Each account connected has an associated Bearer token obtained via the OAuth flow. The token can be used for both client-side as well as server-side requests.

Use a Bearer token in the Authorization header of an HTTP request as shown below:

Authorization: Bearer {token: string}

Here is how you can make a request using cURL:

curl -L -H 'Authorization: Bearer [TOKEN]'[RESOURCE]

You can also authenticate requests to multiple accounts by comma-separating the necessary tokens. For example:

curl -L -H 'Authorization: Bearer token_123,token_456,token_789' \,456,789/storage/links

API Key Authorization 

Bearer tokens are strongly recommended to use to authorize API requests. However, an API Key is also available.

A Kloudless App’s API Key allows API requests to any account connected to that Application. It is therefore not recommended to use API Keys for purposes other than development and testing unless precautions are taken to ensure that users do not access each other’s data. One way to do this is to create a new Kloudless Application programmatically for each user via the Meta API. Only that user’s accounts would then be accessible via that application.

The API key should be kept secret at all times and only be used for server-side requests. It can be found on the App Details page.

Only use API Keys with verified accounts. After an account is connected, transfer its ID and Bearer token to the server-side, where an API request should be performed to verify that the user did connect that account. Once verified, the data can be stored in a database and associated with the application user that connected the account. When performing an API request for this user, this association can be checked to confirm the user has access to the account the API request is being made to.

The procedure above enables your application to safely use the API Key for server-side requests to any account.

Similar to Bearer Tokens, use an API Key as shown below:

Authorization: APIKey {api_key: string}

Here is how you can make a request using cURL:

curl -L -H 'Authorization: APIKey [KEY]'[RESOURCE]

Here are some example requests:

curl -L -H 'Authorization: APIKey XxijaFsSvrgHa8mDvhQ6DF' \

curl -L -H 'Authorization: APIKey XxijaFsSvrgHa8mDvhQ6DF' \

curl -L -H 'Authorization: APIKey XxijaFsSvrgHa8mDvhQ6DF' \

Authenticating users 

To connect user accounts to your application, use one of several options listed below.

This third-party blog post provides an overview of different OAuth grant flows. Kloudless supports a couple of mechanisms to authenticate users:

  • Authenticator JS library pop-up
    Your app can use the Authenticator JS library to authenticate users via a pop-up. Similar to the OAuth 2.0 Implicit Grant flow, the token is provided on the client-side.

  • OAuth 2.0 Authorization Code Grant flow
    Use this if you can authenticate users via a web server.

  • OAuth 2.0 Implicit Grant flow
    Use this if your app is entirely client-side. e.g. a browser-based JavaScript application without backend server logic. Apps with access to a backend server should attempt to use the Authorization Code grant flow instead. We also provide iOS and Android SDKs that authenticate users with an out-of-band mechanism that does not require a HTTP redirect URI to be registered.

  • OAuth 2.0 Out-of-band flow
    Installed apps, or apps on devices that may not receive a redirect, may use the out-of-band flow to render access token information to the DOM. The app can close the window after obtaining the token information.

The mechanisms above are described in more detail below.

Authenticator JS library 

The Authenticator JS library enables your app to open a pop-up that allows the user to choose a service to connect. The pop-up closes once the account has been successfully connected via the OAuth 2.0 Out-of-band flow described in the docs below.

Please see the Kloudless Authenticator GitHub repo for information on how to connect user accounts to your Kloudless app, as well as a full list of configuration options.

OAuth 2.0 

Get started by visiting the App Details page and registering a redirect URL. Users will be redirected to this URL once they have authenticated their account. You can also enable the Implicit Grant flow from the App Details page.

First Leg 

First, re-direct the user to with the appropriate query parameters as mentioned below. Kloudless will redirect the user back to a callback URL you provide.

Query parameters:

  • client_id: Required. This is your Kloudless application’s App ID.

  • response_type: Required. This must be code for the Authorization Code grant flow, or token for the Implicit Grant or Out-of-band flow.

  • state: Required. An arbitrary string provided by you. Kloudless will include this exact value when redirecting back to you via the redirect_uri. You may include any data you’d like to use to maintain state between this request and the callback, but definitely include a random token that is checked in the callback. This prevents CSRF attacks on your users.

  • redirect_uri: Required if more than one Redirect URI is registered in the App Details page. If provided, it must be a URL-encoded version of an absolute URI that exactly matches a registered URI. See notes below for more information.

  • form_data: Optional. A URL-encoded JSON object containing data used to pre-fill default values for fields in the Kloudless authentication forms. For example, the domain of a WebDAV server.

  • oob_loading_delay: Optional. When redirect_uri is set to urn:ietf:wg:oauth:2.0:oob, this parameter indicates the number of milliseconds the loading spinner will last on the callback page before revealing the token. Defaults to 2000.

  • custom_properties: Optional. A URL-encoded JSON object. Use this to store custom data on Account objects.

  • on_error: Optional. By default, when there is an error during authentication, Kloudless will display an error page that contains the details. When on_error is set to redirect, the Kloudless error page will be skipped and the user will be redirected to the redirect_uri with the error code in query parameters.

  • raw[query_name]: Optional. Use this to specify a query parameter for Kloudless to include in the first leg of the OAuth flow for services that authenticate users via OAuth. Kloudless will merge all raw query parameters into the redirect URI the user is redirected to to grant access to their data. The value should be the value of the query parameter. For example, specify include raw[prompt]=consent to include the query parameter prompt=consent in the URI the user is redirected to. Raw query parameters are also supported in regular API requests. More details can be found here.

  • scope: Optional. Describes the services that users are allowed to connect, as well as any specific permissions to request. Defaults to any, which prompts a user to authenticate any supported service.

    To learn more about how to customize the scope query parameter to display the services you prefer, refer to our Knowledge Base article. Here is a brief overview:

    • Provide a space-separated string of service identifiers to limit the services displayed. For example box dropbox will prompt users to choose between connecting a Box account or a Dropbox one.

    • Use a category name instead to display all services in that category. For example, storage displays all cloud storage services, calendar displays all Calendar services, and crm displays all CRM services.

    • If the scope provided resolves to only a single service, Kloudless immediately redirects the user to that service’s authentication flow. For example, setting scope to gdrive immediately redirects the user to the Google login page as part of the Google Drive OAuth flow.

    The list of supported service identifiers can be found in our Core docs.

  • billing_id: Optional. Only applicable for developers with per-user or similar billing that groups usage across multiple accounts under a single ID for billing purposes. Specifies the ID to use to identify this account for billing purposes.

Redirect URIs

Redirect URIs must be HTTPS endpoints unless referencing a local machine or secure private network. This prevents an attacker from obtaining a valid code for a user via eavesdropping or a man-in-the-middle attack.

You may also register a custom URL scheme for mobile applications. This enables your mobile application to receive the access token via the Implicit Grant flow.

For installed apps, you may register the URI urn:ietf:wg:oauth:2.0:oob to render data on the callback page’s HTML DOM that would have be sent via the redirect. Your app would need to obtain the data from the DOM prior to closing the window.

Here is an example of a URL to use for the first leg of the OAuth flow:

# Authenticate a user and redirect back to http://localhost:8080/callback

Store extra information on Account objects (optional)

The result of the OAuth flow is an Account object associated with your Kloudless project. Apps can associate custom metadata such as user IDs with this object by using the custom_properties query string parameter during the OAuth flow to set the metadata to store.

The custom_properties query parameter must be a URL-encoded JSON object. Here is an example that stores the data {"name": "demo"} on an Account object (the full query string is not shown):

Advanced: Pre-Filling Authentication Forms (optional)

Some services require additional information about a user’s account or the third-party service during the authentication process. In these cases, Kloudless prompts the user to enter information required, such as the location of the server being connected to. However, if your application is already aware of some of the information required, it can provide the data to Kloudless via the form_data query parameter during the authentication flow. Kloudless will pre-fill the data for the user in the form, enabling the user to avoid having to enter the information in manually.

Here are a list of services and the attributes each support pre-filling via form_data:

  • box (admin):

    • enterprise_id: ID of the Box Enterprise to connect to. This is only required when authenticating admin accounts, if your Box app is configured to use JWT Authentication. Refer to Third-Party Configuration for more information.
  • caldav:

    • domain: Domain of CalDAV server to connect to. e.g.
  • cmis:

    • repository_url: The AtomPub url for the CMIS server. e.g.
  • cq5:

    • server: The full URI of the CQ5 server, e.g.
    • username: Username registered in the CQ5 server.
    • password: Password registered in the CQ5 server.
  • dynamics:

    • resource: The url of your Microsoft Dynamics instance. e.g.
  • egnyte:

    • domain: Your company specific Egnyte domain. e.g. company in
  • ftp:

    • domain: The full URI of the FTP server. e.g. ftps://
    • sftp:
      • domain: The host and port (optional) of the SFTP server. e.g.
  • jive:

    • community: The url of your Jive community.
  • pipeliner:

    • team_space_id: ID of the Pipeliner Team Space (admin only).
  • smb:

    • domain: The domain of the SMB server.
  • webdav:

    • protocol: “http” or “https”
    • host: Fully qualified domain name of the WebDAV server.
    • port: The port number of the WebDAV server.
    • path: The path of the WebDAV service.
  • s3_compatible:

  • aliyun_oss:

Handling the response from Kloudless 

The user will proceed through the authentication process that enables them to grant access to their account to your application.

Authorization Code Grant flow

If a user successfully grants access, Kloudless will redirect back to the redirect_uri provided in the first leg with the state provided earlier and a code. The code is an authorization code that is valid for 5 minutes.

Here is an example URL:

# If the redirect_uri was http%3A%2F%2Flocalhost%3A8080%2Fcallback (http://localhost:8080/callback):

If a user denies access, or there is an error during authentication, Kloudless will instead redirect back with the query parameter ‘error’ in addition to state. A human-readable error message may also be present in error_description. For example:


See the Errors section below for more information on error codes.

Implicit Grant flow

Similar to the Authorization Code Grant flow above, Kloudless will redirect back to the redirect_uri provided. However, Kloudless will provide the access token (OAuth 2.0 Bearer token) in the fragment portion of the URL for access via client-side JavaScript. See the Obtaining an Access Token section below for more information.

Similarly, the error, state and error_description fields will be provided in the fragment if an error occurs. For example:


Out-of-band installed app flow.

A redirect will not occur. Kloudless will instead render the access token data in the HTML DOM. See the Obtaining an Access Token section below for more information.

Similarly, the error, state and error_description fields will be provided via the DOM as well.


The error code present in error will be one of the following:

  • invalid_request: The request may be missing a required parameter, contain incorrect parameters, or is malformed in some other way.

  • access_denied: The user or service denied access to the user’s account.

  • unsupported_response_type The value of the response_type field is incorrect.

  • invalid_scope: The scope field’s value is malformed.

  • temporarily_unavailable: Your application is being rate-limited, or the service is otherwise unavailable.

Errors with the Redirect URI will instead display an HTML page indicating the issue with the URI, as it would not be possible to transmit the error data via the redirect.

Obtaining an Access Token 

The Access Token can be used in the Authorization header to perform API requests to Kloudless. This token provides complete access to the user’s account and must be kept confidential, with only trusted applications and the account owner having access to it.

Authorization Code Grant flow

The Access Token can be obtained by exchanging the authorization code retrieved earlier via a POST request to with the following parameters in the body:

  • grant_type: Required. Must be authorization_code.

  • code: Required. Must be the code provided via the redirect.

  • redirect_uri: Required if a redirect URI was included in the first leg of the OAuth flow when requesting an authorization code. This must be the same value originally provided.

  • client_id: Required. Must be the Kloudless App ID of the application.

  • client_secret: Required. Must be the Kloudless Client Secret of the application.

The parameters must be URL-encoded and sent via the “application/x-www-form-urlencoded” format. For example, the body of the request could be:


Here is an example of performing the request using cURL:

curl -X POST -d 'grant_type=...the remaining string above'

If successful, the response to the request will contain a JSON object with the following attributes:

  • access_token: A string representing the access token. Save this securely for use with future API requests to this account.

  • token_type: Will be ‘Bearer’.

  • scope: The scope granted to the access token. As of the current time, this will be the requested scope. In the future, Kloudless may return a subset of the requested scopes if the user grants partial access to their account.

  • account_id: The Kloudless ID of the account that was connected to the application.

If unsuccessful, error data will be provided in the response instead. See the Errors section below for more information.

Client Secret

The Client Secret provides a means to impersonate an App during the OAuth 2.0 Authorization Code Grant flow. Sharing the Client Secret with a third-party enables them to prompt a user to grant access to their account on behalf of your Kloudless App, and obtain bearer tokens to access that user’s account. Client Secret must therefore be kept confidential and only used on the server-side.

An App’s Client Secret can be found on the App Details page of the developer portal. Although all team members of shared Kloudless Apps have access to the Client Secret, possessing it only allows obtaining bearer tokens to access accounts newly connected by that team member. The API Key, which provides app-wide access to all existing and new accounts, is only accessible to app Admins or Owners. The Client Secret also cannot be exchanged for bearer tokens, or used to authorize actual API requests, unlike API Keys.

Implicit Grant flow

If successful, the fragment section of the URL will contain the access token information mentioned below:

  • access_token: A string representing the access token. Save this securely for use with future API requests to this account.

  • token_type: Will be ‘Bearer’.

  • scope: The scope granted to the access token. As of the current time, this will be the requested scope. In the future, Kloudless may return a subset of the requested scopes if the user grants partial access to their account.

  • state: The value provided in the state parameter in the first leg of the OAuth flow.

Each value will be URL-encoded if necessary. Here is an example:


Verify the token

For security purposes, it is important to verify that the access token was granted to your application and not another application. Otherwise, your application could be vulnerable to a Confused Deputy attack as described in this section of the RFC.

To validate the token, perform a GET request to with the header Authorization: Bearer TOKEN where TOKEN is the access token.

For example:

curl -X GET -H "Authorization: Bearer ABC123ABC"

A valid token will return a response with a 200 status code and a JSON body with the following attributes:

  • client_id: The ID of the application the token was granted to.

  • account_id: The ID of the account the token provides access to.

  • scope: The scope granted to the access token.

You must verify that the client_id matches your Kloudless Application ID exactly. If it does not, do not use the token, and feel free to revoke it. If it does match, you may proceed with using the token in your application.

If you have existing knowledge of the account the token belongs to, please also verify the account_id matches the ID of that account.

If the token has expired, has been revoked or is no longer valid, the response will instead have a 400 status code with the body:

{"error": "invalid_token"}

By design, no other information is provided.

Out-of-band installed app flow

This section is very similar to the Implicit Grant flow above.

However, instead of attributes present in the fragment of the redirected URL, each attribute will be rendered on the DOM in <meta /> elements, with the id attribute of the element identifying the type of data and the data-value attribute providing its value. Your application should retrieve elements by id to obtain the information provided in the attributes.

There will also be text on the page providing the user with the access token in case you would prefer the user copy it into your application.

For example:

<!DOCTYPE html>
    <meta class="token-data" id="access_token" data-value="ABC123ABC" />
    <meta class="token-data" id="token_type"   data-value="Bearer" />
    <meta class="token-data" id="scope"        data-value="gdrive" />
    <meta class="token-data" id="state"        data-value="CSRF_PREVENTION_TOKEN" />
      You have successfully connected your account.
    <p>Secret Access Token: <code>ABC123ABC123</code></p>

Similarly, the error, state and error_description fields will be provided via DOM <meta /> tags if an error occurs.

You may close the window or redirect away after obtaining the information from the DOM. There may be other DOM elements present on the page, so it is important to only check for <meta /> elements to obtain information from.

You must validate the access token prior to using it, as mentioned above in the Implicit Grant flow. This avoids security vulnerabilities such as the Confused Deputy problem.


Unsuccessful requests will result in one of the following error codes returned in the error field, as well as a human-readable error_description if available:

  • invalid_request: The request contains incorrect parameters or is otherwise malformed.

  • invalid_grant: The provided authorization grant (e.g. the authorization code) is invalid or expired.

  • unauthorized_client: The client is not authorized to use this grant type.

  • unsupported_grant_type: An incorrect grant type was used in the request.

  • invalid_scope: The scope requested is invalid or malformed.

Revoking Access Tokens 

Once a token is revoked, it can no longer be used for API requests.

To revoke a token, perform a DELETE request to, with a query parameter token containing the token to revoke.

For example:

curl -X DELETE

A response with the status code 204 will be returned if the revocation is successful or the token does not exist.

It is also possible to revoke all tokens associated with a Kloudless Account, while retaining specific tokens used with that Account, using the keep_tokens query parameter:


The request above will not alter tokens ABC and DEF, but revoke any other tokens associated with the Account accessible via ABC and DEF. Note that all tokens specified must be valid and belong to the same Kloudless Account.

When using keep_tokens, a response with the 204 status code is returned if the revocation process is successful after validating all tokens specified haven’t expired and belong to the same Kloudless account.

Exchanging Access Tokens 

Existing Access Tokens and API Keys can be used to provision tokens with access that is equal to or less than the token used to authorize the request. The exchange can be performed according to the OAuth Working Group’s Token Exchange Draft.

To provision a new token, perform a POST request to with the following parameters in the request body:

  • grant_type: Required. The type of OAuth grant used. Must be urn:ietf:params:oauth:grant-type:token-exchange.

  • subject_token_type: Required. Identifier that indicates the type of token used when performing the request. Must be one of:

    • urn:ietf:params:oauth:token-type:access_token - Access token
    • api_key - API Key
  • subject_token: Required. Token used to authorize the exchange.

  • resource: A URL representing the resource that the token is being requested for. Currently, this should always represent the Kloudless Account the access token should be able to access. For example, if the new token returned should be able to access the account with ID 123, the resource in this request should be
    Optional when using urn:ietf:params:oauth:token-type:access_token as the subject_token_type. Required otherwise.

  • scope: Required. A list of space-delimited strings representing the desired scope of the requested token.

    • If the new token should have permissions as close to subject_token as possible, follow the steps below:
      1. If subject_token is an API Key, use the effective_scope attribute of the Account represented by resource as the scope.
      2. If subject_token is a Bearer Token, use its scope value, which is available from the token verification endpoint or returned in the original data provided when completing the Kloudless OAuth flow. The effective_scope attribute of the Account accessible via the Bearer token can also be retrieved and set as the scope in this request if broad access to the Account is acceptable.
    • If the new token should have permissions more limited than those present for the subject_token, set scope to a subset of the scope accessible via the subject_token as described in our Knowledge Base article.
      • Note: If subject_token is an API Key, any scope provided is restricted to the effective_scope of the Account represented by resource.

Refer to the Authorization Code Grant flow section above for details on the API response format. An example is provided below.

Example Request:

curl -X POST` \
    -d 'grant_type=urn:ietf:params:oauth:grant-type:token-exchange' \
    -d 'scope=default' \
    -d 'subject_token_type=api_key' \
    -d 'subject_token=ABCDEF1234' \
    -d 'resource='

Example Response:

  "access_token": "TOKEN12345",
  "token_type": "Bearer",
  "account_id": 123,
  "scope": "google_calendar"


Each Account represents a software service account that a user has connected to your app.

For billing purposes, any account with enabled set to true, or without a disable_reason, is considered a Connected Account. Delete Accounts in order for them to no longer be considered “connected” the following month for billing purposes. Accounts that are deleted will retain their IDs unless erased for GDPR compliance purposes. All upstream connector IDs, such as the IDs of files, will therefore continue to decode appropriately if the account is reconnected by the user. Accounts disabled via this API, rather than due to a valid disable_reason code, are still considered connected for billing purposes.

  • id Unique identifier for this account

  • account Account identifier that can be used to display the user. This is usually the account’s email address, but can be other strings, such as the user’s name if the email cannot be obtained (e.g.: for Evernote).

  • service Service identifier. Indicates which software service the account is for. For all available values, see the list of supported services.

  • service_name A displayable name for the service. Examples: Google Drive, Amazon S3, Dropbox.

  • enabled If the account’s tokens have expired, or the account is inaccessible, the account will be disabled and this value will be false. Previously called active, which is now deprecated and will be removed in v2.

  • disable_reason If present, indicates one of the following reasons for the account being disabled.

    • inaccessible: The account is no longer accessible by Kloudless.
    • proxy-inaccessible: The Proxy Connection is no longer accessible.
    • plan-change: The new Plan does not support this type of account.

    Previously called deactivation_code, which is now deprecated and will be removed in v2.

  • admin True if the account was authenticated using the admin flow. These accounts are intended to grant access to org-wide data, either by virtue of the admin user having access to all data (such as for SharePoint) or by impersonating individual users.

    We support the admin parameter for the following services:

    • box
    • gdrive
    • dropbox
    • google_calendar
    • ms_teams
    • onedrivebiz
    • outlook_calendar
    • outlook_email
    • sharepoint
    • slack

    Not all services require admin authentication to provide access to all data. e.g. s3, sharefile.

  • internal_use Internal Development: This indicates that the account is only used internally for development, testing, and similar purposes. This enables Kloudless to waive usage fees for these accounts.

  • created ISO 8601 timestamp indicating when the account object was created (first connected).

  • modified ISO 8601 timestamp indicating when the account object was modified.

  • last_request An ISO 8601 timestamp indicating the last time an API request was received for this account. Note that connected accounts without recent requests may still be billed for due to background activity such as keeping tokens refreshed, monitoring changes, and webhooks.

  • user_id ID of the user in the service. Corresponds to the User ID returned from the Team endpoint for admin accounts. null if unavailable or not applicable.

  • quota Only provided when retrieving metadata of a specific account. It is a dictionary with:

    • used space in bytes used by the account (can be null for some services).
    • total space in bytes that that account can use in total (can be null for some services).
  • effective_scope The Kloudless scopes granted to this Account. This represents the account’s capabilities and permissions and may be different than the scopes requested during the authentication process. Refer to our Knowledge Base article for more information on the format of this string.

  • apis The Kloudless unified APIs whose endpoints are accessible by this account.

  • custom_properties Store up to 2000 characters of arbitrary custom metadata in this object, such as the ID of the user that connected this account and other information.

  • type Will always be account.

  • api Will always be core.

Please contact us at if you would like to retrieve the credentials Kloudless uses to connect to the underlying third-party account. This is useful for direct requests to a service’s API, bypassing Kloudless. The following attributes can be added to the account metadata:

  • token The third-party account’s token/key/secret, that is used by Kloudless to access the account. Kloudless automatically refreshes OAuth 2.0 tokens if necessary.

  • token_secret The OAuth 2.0 token secret, if any.

  • account_id The third-party account’s ID. This is useful when determining how to construct independent requests directly to a third-party service’s API. "me" can be used as an alias for the account_id when making request with a Bearer Token and not an API Key, since Bearer Tokens uniquely identify an account.

  • token_expiry ISO 8601 timestamp indicating when the token used to access the account expires, if at all. e.g.: For OAuth 2.0, this refers to the expiry time of the access token.

  • refresh_token_expiry ISO 8601 timestamp indicating when the OAuth 2.0 refresh token expires, if using OAuth 2.0 and refresh tokens are present.

List Accounts 

list accountsGET /accounts{?enabled,page_size,page,admin,ordering,search}

The response contains the following information:

  • total Total number of objects

  • count Number of objects on this page

  • page Page number

  • objects List of account objects

  • type Will always be object_list

  • api Will always be meta

  • Parameters
  • enabled
    boolean (optional) 

    Retrieves only enabled/disabled accounts, if present.

    Choices: True False

    number (optional) Default: 10 

    Number of objects in each page. The page_size must be between 1 and 1000.

    number (optional) 

    Page to return. page_size number of objects will be returned on each page. By default, the first page is returned. The page parameter can be used to request further objects.

    page must be greater than 0.

    boolean (optional) 

    Retrieves only admin/non-admin accounts, if present.

    Choices: True False

    string (optional) Default: -updated_at 

    Fields to order results on. Prefix with a - for descending order.

    Choices: id service account created_at updated_at last_request

    string (optional) 

    Only return results where one of the following fields matches the search phrase case-insensitively:

    • id

    • account

    • effective_scope

    • service

    • service_name

    • object_definitions

    • custom_properties

  • Response  200Toggle
  • Headers

    Content-Type: application/json


        "total": 2,
        "count": 2,
        "page": 1,
        "objects": [
                "id": 90817234,
                "account": "",
                "service": "box",
                "service_name": "Box",
                "admin": false,
                "enabled": true,
                "internal_use": false,
                "created": "2015-03-17T20:42:17.954885Z",
                "modified": "2015-03-17T20:42:17.954885Z",
                "user_id": "uX1jd9af",
                "custom_properties": {
                    "your": "data"
                "last_request": "2019-09-18T21:12:13.851881Z",
                "type": "account",
                "api": "core",
                "id": 6535892,
                "account": "",
                "service": "egnyte",
                "service_name": "Egnyte",
                "admin": false,
                "enabled": true,
                "internal_use": false,
                "created": "2015-03-17T20:42:18.627533Z",
                "modified": "2015-03-17T20:42:18.627533Z",
                "user_id": null,
                "custom_properties": {
                    "your": "other data"
                "last_request": null,
                "type": "account",
                "api": "core",
        "type": "object_list",
        "api": "core"

Import an Account 

import an accountPOST /accounts

Account creation is usually handled via Kloudless Authentication. However, this account creation endpoint can be used to import account and token information into Kloudless. This is useful when your app has already authenticated a user and wishes to migrate the credentials into Kloudless to use the Kloudless API endpoints instead.

Additional attributes present in the response:

  • kloudless_bearer_token The response will contain a Kloudless Bearer token to use to authorize API requests to the account.

Here are the required attributes that must be included in the request body:

  • account Described above. For services that authenticate via a username and password, this must be the username. Can be omitted if source is specified.

  • service Described above.

The following parameters are required for OAuth services:

  • token The access token used to authenticate requests to the service. Can be omitted if source is specified.

The following parameters are required for services that require a username and password to authenticate access:

  • password The password or key used to authenticate requests to the service.

In addition, the following optional parameters may be provided:

  • scope The Kloudless scopes to grant to the account. This represents the requested capabilities and permissions. The scope actually provided will be available in the effective_scope attribute in the response. The effective_scope will differ based on considering the account’s available capabilities. Refer to our Knowledge Base article for more information on the format of this string.

  • custom_properties Store up to 2000 characters of arbitrary custom metadata in this object, such as the ID of the user that connected this account and other information.

  • token_secret The OAuth token secret.

  • refresh_token The OAuth 2.0 refresh token.

  • token_expiry Described above.

  • refresh_token_expiry Described above.

  • admin Described above.

  • billing_id: Described above.

  • source The ID of another account owned by the same application to use as a template to create the new account. If provided, values for all other optional attributes not specified in the request body will be populated from this existing account instead.

    For example, a developer could prompt their user to connect a Google Calendar account through the Kloudless OAuth flow using Custom Raw Scopes that include Google Drive scopes as well. This enables the developer to avoid having to prompt the user to connect Google Drive separately. However, the resulting account is still a google_calendar account. Since it has access to Google Drive, it can be used as a source in a request to this endpoint to obtain a gdrive account.

Certain services require a few additional parameters as mentioned below.

  • box

    • OAuth 2.0 requires no additional parameters.
    • For the JWT Authentication described on the Custom OAuth Keys page of the Developer Portal under the section for custom Box admin keys, include the following attributes:
      • token: The token that is obtained by OAuth authentication via the non-admin Box credentials of the Kloudless App.
      • enterprise_id: The ID of the Enterprise this account represents.
      • admin: true for admin accounts.
      • service: box
      • (Optional) account: A unique identifier for this account, or the unique identifier of an existing account to overwrite it. If not set, this will be inferred and set automatically.
    • Since no default User ID is specified, all JWT API requests for user data must impersonate a valid Box user.
  • sharefile

    • domain The user’s ShareFile domain. This can be obtained from the response to a request for an access token.
  • egnyte

    • domain The user’s Egnyte domain. This can be obtained from the URL users use to access their Egnyte account:
  • sharepoint, onedrivebiz

    • Admin accounts
    • Non-admin accounts
      • token: A JSON string containing the access tokens for SharePoint Online/OneDrive for Business REST API and the Graph API. For example:
        '{"oauth": "sharepoint/onedrivebiz REST API access token",
          "graph": "graph API access token"}'
      • refresh_token: A JSON string containing the refresh tokens for SharePoint Online/OneDrive for Business REST API and the Graph API (see token above).
  • sharepoint2013

    • domain The URL of the user’s SharePoint domain or site.
  • smb

    • domain The host (and port if non-default) of the SMB server. For example,
  • cmis, alfresco, alfresco_cloud

  • webdav

    • protocol: The WebDAV URL protocol. e.g. http
    • host: The WebDAV host URL. e.g.
    • port: The WebDAV port. e.g. 80
    • path: The WebDAV path. e.g. webdav
  • caldav

    • protocol: The CalDAV URL protocol. e.g. http
    • domain: The CalDAV URL Domain. e.g.
  • cq5

    • server: The full URI of the CQ5 server, e.g.
    • username: Username registered in the CQ5 server.
    • password: Password registered in the CQ5 server.
  • hubspot

  • jive

  • salesforce

    • instance_url Identifies the Salesforce instance to which API calls should be sent. e.g.
    • identity_url Identity URL that can be used to both identify the user as well as query for more information about the user. e.g.
  • dynamics

    • resource The URL of the user’s Dynamics CRM portal. e.g.
  • oracle

    • server_url The Oracle Sales Cloud Host Server URL. e.g.
  • pipeliner

    • team_space_id The Pipeliner Team Space ID. e.g. ts1_TeamSpace_Id
  • exchange and exchange_email

    • server: The full URI of the Exchange server, e.g.
    • (Optional) primary_smtp_address: The primary SMTP address. It is optional under certain cases, depending on the server configuration and the format of the username entered. Kloudless uses NTLM to authenticate and do not rely on Autodiscover, thus requires the primary SMTP address to be included under most circumstances.
  • office365_ps

    • auth_codes: Authorization Codes generated by the PSMSOAuth PowerShell module.
    • password: "fake"
  • powershell

    • domain: The domain name or IP address of the remote computer to run commands on. This is used in the ComputerName parameter of the Invoke-Command PowerShell cmdlet. Please refer to Microsoft Docs for more details.
  • s3

    • enable_transfer_acceleration: If False, won’t attempt to use S3 Transfer Acceleration for uploads/downloads. This saves a few extra metadata queries every minute during uploads/downloads if it is known that S3 Transfer Acceleration won’t be used. Default value is True.

Since token information is being imported, the credentials used to authenticate the user and obtain those tokens must be entered into the Kloudless Developer Portal. Otherwise, Kloudless will not be able to use the tokens to perform requests.

Please contact us for more information on how to migrate your app to our service with close to no downtime.

Example request:

curl -H 'Authorization: APIKey XxijaFsSvrgHa8mDvhQ6DF' \
    -H 'Content-Type: application/json' \
    -d '{"account": "", "service": "gdrive", "token": "foo", "token_secret": "bar"}' \
    -XPOST ''

Example request that copies an existing account:

curl -H 'Authorization: APIKey XxijaFsSvrgHa8mDvhQ6DF' \
    -H 'Content-Type: application/json' \
    -d '{"source": "12345", "service": "gdrive"}' \
    -XPOST ''
  • RequestToggle
  • Headers

    Authorization: APIKey [KEY]
    Content-Type: application/json


      "account": "",
      "service": "gdrive",
      "token": "foo",
      "token_secret": "bar"
  • Response  201Toggle
  • Headers

    Content-Type: application/json


        "id": 92386572,
        "account": "",
        "service": "gdrive",
        "service_name": "Google Drive",
        "admin": false,
        "enabled": true,
        "internal_use": false,
        "created": "2015-05-15T20:00:00Z",
        "modified": "2015-05-15T20:00:00Z",
        "last_request": null,
        "token_expiry": null,
        "refresh_token_expiry": null,
        "user_id": null,
        "type": "account",
        "api": "core",

Retrieve an Account 

retrieve an accountGET /accounts/{account_id}/{?enabled,retrieve_tokens,retrieve_full}
  • Parameters
  • enabled
    boolean (optional) 

    Retrieves only an enabled/disabled account, if present.

    Choices: True False

    boolean (optional) Default: False 

    Retrieves token, token_secret, token_expiry, refresh_token_expiry and account_id for an account. Refer to the description of attributes above for more information. Please contact to enable access.

    Choices: True False

    boolean (optional) Default: True 

    Queries the service for additional information and includes it in the metadata for the account. At the current time, this option populates the quota field. This parameter can be set to False for efficiency reasons if only the other account metadata is required.

    Choices: True False

  • Response  200Toggle
  • Headers

    Content-Type: application/json


        "id": 90817234,
        "account": "",
        "service": "box",
        "service_name": "Box",
        "admin": false,
        "enabled": true,
        "internal_use": false,
        "created": "2015-03-17T20:42:17.954885Z",
        "modified": "2015-03-17T20:42:17.954885Z",
        "token": "ABC123",
        "token_secret": "",
        "refresh_token": "XYZ456",
        "token_expiry": "2015-04-17T20:42:17.954885Z",
        "refresh_token_expiry": null,
        "account_id": "abc123xyz456",
        "user_id": "uX1jd9af",
        "quota": {
            "used": 316317438,
            "total": 2627241831
        "custom_properties": {
            "your": "data"
        "last_request": "2019-09-18T21:12:13.851881Z",
        "type": "account",
        "api": "core",

Update an Account 

Update an AccountPATCH /accounts/{account_id}

When importing account/token information, you may wish to update Kloudless’ knowledge of tokens if you refresh them or obtain new tokens for the account. This endpoint will allow you to update the account with new information.

Here are the properties that can be updated:

  • enabled

  • service

  • account (considered to be the username for password-based services)

  • For OAuth services:

    • token
    • token_secret (for OAuth-based services only)
    • refresh_token (for OAuth-based services only)
    • token_expiry
    • refresh_token_expiry
  • For password-based services:

    • password
  • custom_properties

Any of the additional parameters supported by a service during import are also supported during updates where appropriate.

The new object will be returned on success.

Example request:

curl -H 'Authorization: Bearer [TOKEN]' \
    -H 'Content-Type: application/json' \
    -XPATCH -d '{"enabled": false}' \

Note that setting an account to disabled will cease attempts to refresh the account’s refresh_token causing the token to expire after the refresh_token_expiry if present. The user would then have to reconnect their account to re-enable it.

  • RequestToggle
  • Headers

    Authorization: Bearer [TOKEN]
    Content-Type: application/json


        "enabled": false,
  • Response  200Toggle
  • Headers

    Content-Type: application/json


        "id": 90817234,
        "account": "",
        "service": "box",
        "service_name": "Box",
        "admin": false,
        "enabled": false,
        "disable_reason": "inaccessible",
        "internal_use": false,
        "created": "2015-03-17T20:42:17.954885Z",
        "modified": "2015-05-15T06:12:00Z",
        "user_id": "uX1jd9af",
        "last_request": "2019-09-18T21:12:13.851881Z",
        "type": "account",
        "api": "core",

Delete an Account 

Delete an AccountDELETE /accounts/{account_id}

This removes an account from the application, and deletes all associated data such as tokens, event metadata, links, etc. The account will no longer be accessible.

The account ID and identifiers are preserved so that if the user re-connects the same account to your application in the future, the account ID would be the same for convenience.

If you would like to permanently erase account ID information, please contact us to enable access.

Example request:

curl -L -H 'Authorization: Bearer [TOKEN]' \
  • Response  204