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]' https://api.kloudless.com/v1/[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' \
    https://api.kloudless.com/v1/accounts/123,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]' https://api.kloudless.com/v1/[RESOURCE]

Here are some example requests:

curl -L -H 'Authorization: APIKey XxijaFsSvrgHa8mDvhQ6DF' \
    https://api.kloudless.com/v1/accounts?enabled=True

curl -L -H 'Authorization: APIKey XxijaFsSvrgHa8mDvhQ6DF' \
    https://api.kloudless.com/v1/accounts/1/storage/files/fL3Rlc3QucG5n/contents

curl -L -H 'Authorization: APIKey XxijaFsSvrgHa8mDvhQ6DF' \
    https://api.kloudless.com/v1/accounts/1/storage/links

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 https://api.kloudless.com/v1/oauth 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
https://api.kloudless.com/v1/oauth/?client_id=APP_ID&response_type=code&redirect_uri=http%3A%2F%2Flocalhost%3A8080%2Fcallback&state=CSRF_PREVENTION_TOKEN

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):

https://api.kloudless.com/v1/oauth/?custom_properties=%7B%22name%22%3A%22demo%22%7D&...

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. caldav.company.com.

• cmis:

  • repository_url: The AtomPub url for the CMIS server. e.g. https://cmis.alfresco.com/api/-default-/public/cmis/versions/1.1/atom.

• cq5:

  • server: The full URI of the CQ5 server, e.g. https://cq5.example.com.
  • 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. https://mydomain.crm.dynamics.com.

• egnyte:

  • domain: Your company specific Egnyte domain. e.g. company in company.egnyte.com.

• ftp:

  • domain: The full URI of the FTP server. e.g. ftps://ftp.example.com:21.
  • sftp:
    • domain: The host and port (optional) of the SFTP server. e.g. example.com:22.

• 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:

  • domain: Domain name and optional port of the S3-compatible service to connect to. e.g. datastore.s3-like.com:443.

• aliyun_oss:

  • domain: Domain name of Object Storage Service endpoint to connect to. e.g. oss-us-east-1.aliyuncs.com.

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):
http://localhost:8080/callback?code=ABC123ABC&state=CSRF_PREVENTION_TOKEN

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:

http://localhost:8080/callback?error=access_denied&error_description=User%20cancelled%20authentication

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:

http://localhost:8080/callback#error=access_denied&error_description=User%20cancelled%20authentication

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.

Errors ¶

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 https://api.kloudless.com/v1/oauth/token 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:

grant_type=authorization_code&code=ABC123ABC&redirect_uri=http%3A%2F%2Flocalhost%3A8080%2Fcallback&client_id=APP_ID&client_secret=CLIENT_SECRET

Here is an example of performing the request using cURL:

curl -X POST -d 'grant_type=...the remaining string above' https://api.kloudless.com/v1/oauth/token

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:

http://localhost:8080/callback#access_token=ABC123ABC&token_type=Bearer&scope=gdrive&state=CSRF_PREVENTION_TOKEN

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 https://api.kloudless.com/v1/oauth/token with the header Authorization: Bearer TOKEN where TOKEN is the access token.

For example:

curl -X GET -H "Authorization: Bearer ABC123ABC" https://api.kloudless.com/v1/oauth/token

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>
<html>
  <body>
    <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" />
    <p>
      You have successfully connected your account.
    </p>
    <p>Secret Access Token: <code>ABC123ABC123</code></p>
  </body>
</html>

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.

Errors ¶

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 https://api.kloudless.com/v1/oauth/token/, with a query parameter token containing the token to revoke.

For example:

curl -X DELETE https://api.kloudless.com/v1/oauth/token/?token=ABC123ABC

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:

curl -X DELETE https://api.kloudless.com/v1/oauth/token/?keep_tokens=ABC,DEF

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 https://api.kloudless.com/v1/oauth/token 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 https://api.kloudless.com/v1/accounts/123.
  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 https://api.kloudless.com/v1/oauth/token` \
    -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=https://api.kloudless.com/v1/accounts/123'

Example Response:

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

Accounts 

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 support@kloudless.com 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 

Import an Account 

curl -H 'Authorization: APIKey XxijaFsSvrgHa8mDvhQ6DF' \
    -H 'Content-Type: application/json' \
    -d '{"account": "someone@gmail.com", "service": "gdrive", "token": "foo", "token_secret": "bar"}' \
    -XPOST 'https://api.kloudless.com/v1/accounts/'

curl -H 'Authorization: APIKey XxijaFsSvrgHa8mDvhQ6DF' \
    -H 'Content-Type: application/json' \
    -d '{"source": "12345", "service": "gdrive"}' \
    -XPOST 'https://api.kloudless.com/v1/accounts/'

Retrieve an Account 

Update an Account 

curl -H 'Authorization: Bearer [TOKEN]' \
    -H 'Content-Type: application/json' \
    -XPATCH -d '{"enabled": false}' \
    'https://api.kloudless.com/v1/accounts/15'

Delete an Account 

curl -L -H 'Authorization: Bearer [TOKEN]' \
    -XDELETE https://api.kloudless.com/v1/accounts/34