# Box authentication

> UiPath supports the following authentication types for Box. For more information, refer to the [Box authentication documentation](https://developer.box.com/guides/authentication/).

UiPath supports the following authentication types for Box. For more information, refer to the [Box authentication documentation](https://developer.box.com/guides/authentication/).

| Authentication Type | Description | Best For |
|---|---|---|
| **Bring Your Own OAuth 2.0 App** | Uses your own OAuth app with UiPath's callback URL. | Customers managing their own Box app and keys. |
| **Personal Access Token (PAT)** | Uses a Box JWT private key & enterprise/user ID. | Enterprise-level, server-to-server integrations requiring app-only or enterprise-wide access without user interaction. |

## Authentication types details

### Bring Your Own OAuth 2.0 App

| Field | Description |
| --- | --- |
| **OAuth API Key** | Box Client ID. |
| **OAuth API Secret** | Box Client Secret. |
| **Scope** | Predefined or custom Box scopes. |

:::important
Configure this redirect URI in your Box app: `https://{yourDomain}/provisioning_/callback`.
:::

### Personal Access Token (PAT)

| Field | Description |
| --- | --- |
| **OAuth API Key** | Box **Client ID** from the Box Developer Console. |
| **OAuth API Secret** | Box **Client Secret** from the Box Developer Console. |
| **Scope** | Scopes selected in Box and required for automation. |
| **JWT Audience** | Example: `https://api.box.com/oauth2/token` |
| **JWT Base64 Encoded Key** | Your Box app **Base64-encoded private key** from the JWT app configuration. |
| **JWT Issuer** | The Box app **Client ID**, used as the JWT `iss` claim. |
| **JWT Sub Type** | Must be **enterprise** or **user** based on desired impersonation target. |
| **JWT Subject** | The **Enterprise ID** (if sub type = enterprise) or **User ID** (if sub type = user). |

## Creating a Box app

Before connecting UiPath to Box, you must create an application in the **Box Developer Console**. For more information, refer to the [Box Developer Documentation](https://developer.box.com/).
 
1. Open **Developer Console**
2. Select **Create New App**
3. Choose one of the following depending on your intended authentication type:
   * **OAuth 2.0 (User Authentication)** → used for BYO OAuth
   * **OAuth 2.0 with JWT** → used for PAT in UiPath IS

After creating the Box app, collect:
* **Client ID**
* **Client Secret**
* **App Scopes**
* **Private Key (JWT apps only)**
* **Enterprise/User ID**

:::important
For Bring Your Own OAuth 2.0 App, add UiPath's callback URL to your Box app: `https://{yourDomain}/provisioning_/callback`.
:::

## Understanding Box scopes

Box requires explicit permission selection known as "scopes". The following table lists the common predefined scopes for Box apps.

| Scope | Description |
|---|---|
| **root_readonly** | Read-only access to all content the user/account can access. |
| **root_readwrite** | Full read/write access to files and folders. |
| **manage_groups** | Manage Box groups. |
| **manage_enterprise_properties** | Manage enterprise metadata and properties. |
| **manage_data_retention** | Configure retention policies and legal holds. |
| **sign_requests.readwrite** | Create and manage Box Sign requests. |
| **manage_app_users** | Manage application users. |
| **manage_managed_users** | Manage enterprise managed users. |

Your Box Developer Console must reflect the same scopes that you select while creating the connection. For more details on scopes, please refer to [Scopes](https://developer.box.com/guides/api-calls/permissions-and-errors/scopes/) in Box documentation.

## How to prepare the Box private key

### Step 1 — Download the private key

Download the Box app JSON file that contains the encrypted_private_key and passphrase.

### Step 2 — Decrypt using passphrase

If the key is encrypted, decrypt it:

```
openssl pkcs8 -inform PEM -in private_key.pem -out decrypted_key.pem -passin pass:YOUR_PASSPHRASE
```

This produces the following:

```
-----BEGIN PRIVATE KEY-----
...
-----END PRIVATE KEY-----
```

### Step 3 — Remove PEM headers/footers

Delete these two lines entirely:

```
-----BEGIN PRIVATE KEY-----
-----END PRIVATE KEY-----
```

### Step 4 — Remove all newlines and whitespace

Make the key one single continuous line, no spaces, no line breaks.

Result example:
`MIIG/wIBADANBgkqhkiG9w0BAQEFAASCBK...`

### Step 5 — Base64-encode the cleaned key

Encode the single-line key:

Linux/macOS:
`echo -n "CLEANED_KEY" | base64`

PowerShell:
`[Convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes("CLEANED_KEY"))`

Paste the resulting Base64 output into: **JWT Base64 Encoded Key**. For more information, refer to the [Box authentication documentation](https://developer.box.com/guides/authentication).

## Add the Box connection

1. Select Integration Service from the left rail.
2. From the **Connectors** list, select Box. You can also use the search bar to narrow down the connector.
3. Select **Connect to Box**.
4. You are now directed to the connection page.
5. Enter the required credentials.
6. Select **Connect**.

## Permissions

Accounts should be enabled to access or connect to Box. If not so, contact your administrator and request for the necessary access.

With access to your Box account, UiPath for Box can do the following:

* Read all files and folders stored in Box
* Read and write all files and folders stored in Box
* Manage groups
* Manage enterprise properties
* Manage retention policies
* Enable integrations
* Manage Sign Requests
* Manage app users
* Manage users
* Generate billable Box Sign requests.

For more information, refer to the [Box authentication documentation](https://developer.box.com/guides/authentication/).