# Box

Box is a cloud content management and file sharing platform for businesses. The Sling Box connector extracts data from the Box Content Cloud API, supporting files, folders, users, events, groups, collaborations, metadata templates, and more.

{% hint style="success" %}
**CLI Pro Required**: APIs require a [CLI Pro token](https://docs.slingdata.io/sling-cli/cli-pro) or [Platform Plan](https://docs.slingdata.io/sling-platform/platform).
{% endhint %}

## Setup

The following credentials and inputs are accepted:

**Secrets:**

* `client_id` **(required)** -> Your Box application Client ID
* `client_secret` **(required)** -> Your Box application Client Secret
* `box_subject_id` **(required)** -> Your Box Enterprise ID

**Inputs:**

* `anchor_date` (optional) -> The starting date for historical data extraction (default: 364 days ago). Format: `YYYY-MM-DD`

### Getting Your Credentials

Box uses **OAuth2 Client Credentials Grant (CCG)** for server-to-server authentication. A free Box Developer account includes 10GB storage and full API access.

1. Sign up for a free developer account at <https://account.box.com/signup/n/developer>
2. Go to the [Developer Console](https://app.box.com/developers/console)
3. A **Default App** with Client Credentials Grant (CCG) authentication is automatically created
4. On the **Configuration** tab, find your **Client ID**
5. To access the **Client Secret**, you must enable 2-Step Verification in your Box account:
   * Go to **Account Settings** > **2-Step Verification** and enable it
   * Return to the Developer Console to view the Client Secret
6. Your **Enterprise ID** is on the **General Settings** tab of the Developer Console

{% hint style="warning" %}
**Important:** You must enable 2-Step Verification (2FA) on your Box account before the Client Secret will be visible in the Developer Console.
{% endhint %}

### Using `sling conns`

{% code overflow="wrap" %}

```bash
sling conns set BOX type=api spec=box secrets='{ client_id: your_client_id, client_secret: your_client_secret, box_subject_id: your_enterprise_id }'
```

{% endcode %}

### Environment Variable

See [here](https://docs.slingdata.io/sling-cli/environment#dot-env-file-.env.sling) to learn more about the `.env.sling` file.

{% code overflow="wrap" %}

```bash
export BOX='{ type: api, spec: box, secrets: { client_id: "your_client_id", client_secret: "your_client_secret", box_subject_id: "your_enterprise_id" } }'
```

{% endcode %}

### Sling Env File YAML

See [here](https://docs.slingdata.io/sling-cli/environment#sling-env-file-env.yaml) to learn more about the sling `env.yaml` file.

```yaml
connections:
  BOX:
    type: api
    spec: box
    secrets:
      client_id: "your_client_id"
      client_secret: "your_client_secret"
      box_subject_id: "your_enterprise_id"
```

**With anchor date for historical data:**

```yaml
connections:
  BOX:
    type: api
    spec: box
    secrets:
      client_id: "your_client_id"
      client_secret: "your_client_secret"
      box_subject_id: "your_enterprise_id"
    inputs:
      anchor_date: "2023-01-01"
```

## Replication

Here's an example replication configuration to sync Box data to a PostgreSQL database:

```yaml
source: BOX
target: MY_POSTGRES

defaults:
  mode: full-refresh
  object: box.{stream_name}

streams:
  users:
  groups:
  group_memberships:
  folder_items:
  events:
    mode: incremental
  collaborations:
  collections:
```

**Sync all endpoints:**

```yaml
source: BOX
target: MY_POSTGRES

defaults:
  mode: full-refresh
  object: box.{stream_name}

streams:
  '*':
```

## Endpoints

### Users & Groups

| Endpoint            | Description                                       | Incremental |
| ------------------- | ------------------------------------------------- | ----------- |
| `users`             | Enterprise managed users                          | No          |
| `groups`            | Enterprise groups                                 | No          |
| `group_memberships` | Memberships for each group (iterates over groups) | No          |

### Files & Folders

| Endpoint       | Description                                                     | Incremental |
| -------------- | --------------------------------------------------------------- | ----------- |
| `folder_items` | Items (files, folders, web links) in root folder and subfolders | No          |

### Events

| Endpoint | Description                        | Incremental |
| -------- | ---------------------------------- | ----------- |
| `events` | User events with cursor-based sync | Yes         |

### Collaboration & Organization

| Endpoint             | Description                        | Incremental |
| -------------------- | ---------------------------------- | ----------- |
| `collaborations`     | Pending collaborations             | No          |
| `collections`        | User collections (e.g., Favorites) | No          |
| `metadata_templates` | Enterprise metadata templates      | No          |

### Webhooks

| Endpoint   | Description                             | Incremental |
| ---------- | --------------------------------------- | ----------- |
| `webhooks` | Webhooks configured for the application | No          |

### Box Sign

| Endpoint         | Description        | Incremental |
| ---------------- | ------------------ | ----------- |
| `sign_requests`  | Box Sign requests  | No          |
| `sign_templates` | Box Sign templates | No          |

### Trash

| Endpoint        | Description        | Incremental |
| --------------- | ------------------ | ----------- |
| `trashed_items` | Items in the trash | No          |

To discover available endpoints:

```bash
sling conns discover BOX
```

## Incremental Sync

The Box connector supports incremental sync for the `events` endpoint using cursor-based pagination with `stream_position`:

* **First run:** Fetches all events from the beginning
* **Subsequent runs:** Only fetches events after the last known stream position

All other endpoints use full-refresh mode since the Box API does not support filtering by modification timestamps.

## Rate Limiting

The Box API enforces rate limits per application. The connector automatically:

* Limits to 10 requests/second
* Retries with exponential backoff on 429 (rate limit) responses

## Notes

* **Parent-child endpoints:** The `group_memberships` endpoint iterates over groups fetched by the `groups` endpoint. Similarly, `folder_items` recursively discovers subfolders.
* **Authentication:** The connector uses OAuth2 Client Credentials Grant (CCG) and automatically handles token refresh.
* **Enterprise scope:** The `users` endpoint returns managed users in the enterprise. The `events` endpoint returns enterprise-wide events.

If you are facing issues connecting, please reach out to us at <support@slingdata.io>, on [discord](https://discord.gg/q5xtaSNDvp) or open a Github Issue [here](https://github.com/slingdata-io/sling-cli/issues).