Box API Step by Step

The Box API documentation is terrible, so I'm writing here the steps you will have to follow to setup box integration within you app.

1. Create a box developer account

Simple enough, just go to https://developer.box.com/ and sign up. When you create a developer account, you will automatically get 10GB of storage and a user linked to your email.

2. Create a new Application

Now that you have your developer account, go to https://app.box.com/developers/console and click on "Create New App".

In the next page, you will have a chance to choose between "Custom App", "Enterprise Integration" and "Partner Integration". In our case, we want to connect our back-end to box, so we need an Enterprise Integration for that, choose it and click Next.

The next page gives you the option to choose between OAuth 2.0 or OAuth 2.0+JWT. We need JWT in order to generate tokens without human interaction, choose this option and click Next.

The next page lets you create a unique name for your app, choose one that you like and click "Create App" and then "View Your App".

3. Configuring your application

In the application configuration page, we have some changes to do...

First, change the application access to Enterprise, this is needed so we can upload files as any user in the organization we enter.

Under "Application Scopes" and "Advanced Features", enable all of them, some may be not needed but better safe than sorry... Click on "Save Changes" (top right) after that.

After saving the application config, in the same page, under "Add and Manage Public Keys", click on "Generate a Public/Private Keypar", this will be used in our application back-end to access box programmatically, store the downloaded file somewhere in your computer.

4. Adding your newly created app to your box organization

In order to use some space in box, your application must be added to your "personal" box, this means that we have to authorize our newly created app to use our 10GB of storage to store its files.

To do that, head over to https://app.box.com/folder/0, click on "Admin Console" on the left menu, then click on the cogs icon at the top right corner of the screen, and click "Business Settings".

This will load the configuration panel to change configs of your organization, that is, the box space you have just got when you created your account.

On the top menu, click on Apps, then, under "Custom Applications" click on "Authorize New App", it will ask for an "API Key", it's the "Client ID" of your application, you can find it in the application config panel or in the generated keypar file.

After you paste your client id, it will show a box containing your application name, and all the permissions it is asking, click on "Authorize". Make sure "Access" is set to "All Users", I faced some problems when it was set to "Only App Users of this App".

5. Creating a folder and sharing it with your user

Now you have everything set-up to run your code, one important observation is that application folders/files don't have a proper UI for displaying them, so if you create files/folders in the application space, you will only be able to see them through the API, one way to work around this is to create a folder in the root of your application space, and share it with your user, you will then be able to see it in your user box UI (as a shared folder of course).

Let's do all of that using node,

• Create a new folder to store our node files, and a new index.js inside it.
• Cd into the folder and run npm install box-node-sdk to download the node sdk module.
• Copy the downloaded private/public keypar from step 3 into a file called config.json inside this folder.

In the index.js file, paste the following code:

// Require the Box SDK and the fs module
const BoxSDK = require('box-node-sdk');
const fs = require('fs');

// Read and parse the automatically created Box configuration file.
let configFile = fs.readFileSync('config.json');
configFile = JSON.parse(configFile);

// Initialize the SDK with the Box configuration file and create a client that uses the Service Account.
var sdk = new BoxSDK({
	clientID: configFile.boxAppSettings.clientID,
	clientSecret: configFile.boxAppSettings.clientSecret,
	appAuth: {
		keyID: configFile.boxAppSettings.appAuth.publicKeyID,
		privateKey: configFile.boxAppSettings.appAuth.privateKey,
		passphrase: configFile.boxAppSettings.appAuth.passphrase
	}
});

// Get an app user client
var client = sdk.getAppAuthClient('enterprise', configFile.enterpriseID);

If you run this, it won't do any change in your application's box folder, it will just instantiate things so we can start coding commands in it.

Add the following lines to the same file to create a new folder:

client.folders.create('0', 'Application Folder', (err, data) => {
    if (err) return console.log(err);
    console.log(data)
});

If no errors occurred, you will see the new folder information in your console log, take note of the id field of this folder (a bunch of ids is returned from this, make sure to take the first one right below the field "type").

With this id, comment the previous command and paste this to share the created folder with your user:

client.collaborations.createWithUserEmail('<your-box-developer-user-email>', '<folder-id>', client.collaborationRoles.EDITOR, 
(err, data) => {
    if (err) return console.log(err);
    console.log(data)
});

If everything goes according to plan, you should see an "Application Folder" at https://app.box.com/folder/0, Hooray!

5. CRUD for folders and files

Now that you have everything set-up, you can follow the Box Node SDK Docs to make CRUD operations on files and folders, the hard part is done! Just make sure to manage files under your "Application Folder", otherwise you won't be able to see them in the Box UI.