# Box integration

Box REST API based integration: [Documentation Link](https://developer.box.com/reference)

---

**⚠️ Proxy Configuration:** If your server accesses the internet through a proxy, make sure to whitelist the following domains for DropBox Authentication and storage access: **api.box.com**

---

**⚠️ Restriction:**\
\- REST API does not support **resume** on upload\
\- No mdtm (File modification time) changes.\
\- The REST API does not support streaming during upload. For large file uploads (files larger than **25 MB**), CrushFTP temporarily stores the file in the following location: **CrushFTP Install Folder/box/<\<box username>>**

---

#### 1. Box Custom App Configuration (JWT Authentication)

Create a new **Custom App** at **Box Developer Console** ([Box Console Link](https://app.box.com/developers/console)). Select **Custom App** as the app type to begin configuring your integration with Box services.\
![Box create custom app](Box-integration/box_create_custom_app.png)

CrushFTP uses the **JWT Authentication** (More info: [Box JWT Link](https://developer.box.com/guides/authentication/jwt/)) method provided by Box, not standard OAuth 2.0. When configuring your **Box application**, make sure to select **JWT-based authentication** as the authorization method.

![Box jwt auth](Box-integration/box_jwt_auth.png)

In the Custom App’s configuration, select **App + Enterprise Access** as the authentication method to enable **full access** for server-side integrations within your Box enterprise environment.

![Box app access level](Box-integration/box_app_access_level.png)

Under **Application Scopes**, enable the following permissions by checking the boxes:\
✅ **Write all files and folders stored in Box**\
✅ **Manage users**\
These scopes are required to **allow CrushFTP to upload data** and interact with Box user accounts on your behalf.

![Box app scopes](Box-integration/box_app_scopes.png)

In the **Advanced Features** section, check the box:\
✅ **Make API calls using the as-user header**\
This allows the application **to act on behalf of Box users** within your enterprise using the as-user header.

![Box as user header](Box-integration/box_as_user_header.png)

Generate the **RSA keypair** for **JWT authentication** by navigating to:\
**Configuration -> Add and Manage Public Keys**, then click **Generate a Public/Private Keypair**. It will generate the keypair and display the private key only once — ⚠️ be sure to download and securely store it for later use in your CrushFTP Box JWT configuration.

![Box rsa keypair](Box-integration/box_rsa_keypair.png)

Save your **Custom App** changes: After configuring your Custom App, make sure to **save all** changes.\
⚠️ Go to the Authorization tab and click **Review and Submit**to request **Box Admin approval**. This step is required to activate the app and grant it access to your enterprise data.\
⚠️ **Important**: Any future changes made to the **Custom App** configuration will require re-authorization. The Box Admin must re-authorize the application after each change to ensure continued functionality.

Dwonload JSON file from **Configuration -> App Settings**\
The JSON file should contains:

```
{
  "boxAppSettings": {
    "clientID": "ogXXXXXXXXXXXXXXXX",
    "clientSecret": "laAXXXXXXXXXXXX",
    "appAuth": {
      "publicKeyID": "cgXXXXXXXXX",
      "privateKey": "-----BEGIN ENCRYPTED PRIVATE KEY-----\nXXXXXXXXXXXXXXXXXXXXXnblc=\n-----END ENCRYPTED PRIVATE KEY-----\n",
      "passphrase": "aXXXXXXXXXXXXXXXXXXXXe"
    }
  },
  "enterpriseID": "2XXXXXXXXX5"
}
```

#### 2. Box Remote [VFS](VFS.md) Settings

Select the **Box** remote item type.

**a.) Use JWT JSON File**

**User name** : Enter the Box login email address of the user you want to impersonate.\
**JWT config**: Copy and paste the entire content of the JWT configuration **JSON file** into **this field**. This file was generated when setting up your Box Custom App and contains all required credentials for JWT-based authentication. See above.

![Box vfs congfig file](Box-integration/box_vfs_congfig_file.png)

**b.)** **Store JWT JSON file** is Unchecked:

**User name**: Enter the Box login email address of the user you want to impersonate.\
**Password**: "clientSecret" from the JSON config file\
**Client Id**: "clientID" from the JSON config file\
**Enterprise Id**: "enterpriseID" from the JSON config file\
**Public Key Id**: "publicKeyID" from the JSON config file\
**Private Key**: "privateKey" from the JSON config file\
**Private Key password phrase**: "passphrase" from the JSON config file

![Box vfs settings](Box-integration/box_vfs_settings.png)
