Kloudless API Guide

# Kloudless API interaction

  • Connector Category: Storage
  • Unified APIs Supported: Storage, Activity, Team

# Setting up OAuth keys for Box

To set up OAuth keys for Box, sign in to your Kloudless Account and expand the Adobe CQ5 section in the Custom OAuth keys page. Instructions are provided detailing how to set up the Box application, and the permissions needed to extend access to the Kloudless integration.

# Creating/registering a Box application

You may obtain the OAuth credentials here, then follow the Box guide to setup an application.

# Required scopes

Select the "Read and write all files and folders" scope.

To enable Recent Files or Activity Monitoring you will need to create a webhook. Webhook settings are listed below.

box-custom-webhooks

Please contact us at support@kloudless.com with any questions you may have. We'd be happy to help you get set up.

# Configure admin access OAuth keys

Kloudless supports both OAuth and JSON Web Token (JWT) authentication schemas.

JWT apps can enable the Perform Actions as Users setting so that User Impersonation will work. OAuth 2.0 apps will need to file a support ticket with Box, with their Client ID, to enable the Admin can make calls on behalf of Users scope instead.

Event data may appear for certain users that cannot be impersonated, such as external users granted access through a shared folder. To obtain access to any file/folder without having to impersonate a user to gain access, please contact Box and request the following scope to be enabled for your app: Admin or co-admin can make calls for any content in their enterprise.

Users may be notified of certain actions taken by your application. If you would prefer to avoid this, please request Box to enable the capability for your Box application to suppress notifications . The Box-Notifications: off header can then be included in raw headers passed through in API requests to Box accounts. It will also automatically be used for intermediary tasks, such as temporary folders created when moving files between users in Box organizations.

# OAuth authentication

Admin users can grant access to org-wide data through OAuth 2.0 authentication. Authentication will be performed with the Client ID and Secret configured above.

# JWT authentication

In addition, it is possible to access data in Box organizations using JWT authentication, which Box describes in this guide and is summarized below. This allows access to external data shared with organization users not normally accessible via impersonation.

If you would like to add Box admin accounts using JWT authentication, please follow the steps below.

  1. You should be familiar with the default configuration of your Box application. Now, we will enable a Box Admin Service Account with JWT Authentication as described in the guide linked above.
  2. Generate an RSA Keypair. openssl genrsa -aes256 -out private_key.pem 2048 openssl rsa -pubout -in private_key.pem -out public_key.pem
  3. Keep track of your private key passphrase. You will need to enter it later.
  4. Add the Public Key to your Box application. Locate the Public Key ID and keep track of it.
  5. Configure your Box application to be able to Generate User Access Tokens via the setting on the application configuration page.
  6. Now, in the form above, enter in the following information and click Save:
  • Client Id
  • Client Secret
  • Application Public Key Id
  • Private Key passphrase
  • Upload the private key
  1. For each Box organization you would like to access, request an admin to perform the following steps: Navigate to the Box Admin Console's Business Settings page and click on Apps. Within the Custom Applications section, choose Authorize New App. Enter the Client ID of your Box App into the key field to enable access. Provide your application with the Box organization's enterprise ID. This can be found in the Admin Console under the Account Info tab
  2. You can now either prompt the user to connect their Box account via the web UI, or use the Account Import API to programmatically connect their account.
  • To enable the Kloudless OAuth flow with JWT, you will need a separate Box app that uses OAuth authentication, similar to for authenticating regular non-admin accounts. Configure the OAuth keys for that Box developer app in the non-admin configuration option above. The OAuth authentication will be used by Kloudless to confirm the user has admin access to the Box Enterprise tenant being they are gaining access to via Kloudless.
  • You may also instead import this account via the Account Import API . Include the parameters listed for box in the docs for the Import endpoint. You will need to authenticate the user via non-admin auth as detailed above to obtain a token to provide to Kloudless to confirm the user has admin access to the Box tenant.

The Box application will need additional permissions in order to grant organization-wide access.

# Admin permissions

Your application will need to include the following scopes so admins can grant enterprise-wide access to your application:

  • Manage users
  • Manage groups
  • Manage enterprise properties

Further information on OAuth 2 Scopes for Box can be found here .

# Support

Please contact us at support@kloudless.com with any questions you may have. We'd be happy to help you get set up.

← CalDAV →