> For the complete documentation index, see [llms.txt](https://docs.teleskope.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.teleskope.ai/connectors/saas/filesharing/dropbox.md).

# Dropbox

Connect your Dropbox Business or Enterprise team to Teleskope to catalog and classify files across team folders and member folders, and to surface how each file is exposed — through folder or file membership and through shared links.

## Prerequisites

* A Dropbox **Business** or **Enterprise** team with a **team space** (the default for teams created since 2024). Legacy team configurations without a team space are not supported; enrollment verification reports this.
* Dropbox **team admin** access — required to create the app, authorize it, and read content across the team.
* Teleskope admin access.

## Create a Dropbox App

Teleskope connects to Dropbox with a single team-level app. One app covers the whole team; no per-user authorization is needed.

### Create the app

1. Go to the [Dropbox App Console](https://www.dropbox.com/developers/apps) and sign in as a team admin.
2. Click **Create app**.
3. Choose **Scoped access**.
4. Choose **Full Dropbox** as the access type.
5. Name the app (e.g., **Teleskope**) and click **Create app**.

### Configure permissions

1. In your new app, open the **Permissions** tab.
2. Enable the following scopes:

| Scope                      | Purpose                                                    |
| -------------------------- | ---------------------------------------------------------- |
| `team_info.read`           | Verify the team and confirm a team space exists            |
| `team_data.member`         | Act on behalf of team members to read content and links    |
| `members.read`             | List team members                                          |
| `groups.read`              | Resolve group membership on shared folders                 |
| `files.metadata.read`      | List folders and files                                     |
| `files.content.read`       | Download file content for classification                   |
| `files.team_metadata.read` | List team folders and the team space                       |
| `sharing.read`             | Read shared folder members, file members, and shared links |

3. Click **Submit**.

{% hint style="warning" %}
Submit the permissions **before** generating the refresh token in the next step. Scopes enabled after a token is issued are not included in that token.
{% endhint %}

### Retrieve your credentials

On the **Settings** tab, note the **App key** and **App secret**. You will enter both in Teleskope.

## Generate a Refresh Token

Dropbox does not support a client-credentials grant for team apps, so the team's first token is issued through a one-time browser authorization. Teleskope stores the resulting refresh token and mints short-lived access tokens from it.

1. As a team admin, open the following URL in a browser, replacing `APP_KEY` with your app key:

   ```
   https://www.dropbox.com/oauth2/authorize?client_id=APP_KEY&response_type=code&token_access_type=offline
   ```
2. Approve the request. Dropbox displays an **authorization code**.
3. Exchange the code for a refresh token:

   ```bash
   curl https://api.dropboxapi.com/oauth2/token \
     -u "APP_KEY:APP_SECRET" \
     -d "code=AUTHORIZATION_CODE&grant_type=authorization_code"
   ```
4. From the JSON response, note the `refresh_token` value.

{% hint style="info" %}
The authorization code is single-use and expires quickly. If the exchange fails, repeat step 1 to obtain a new code.
{% endhint %}

### Find your team ID

Teleskope keys the enrollment on your Dropbox team ID (`dbtid:...`). Retrieve it with the access token returned by the exchange above:

```bash
curl https://api.dropboxapi.com/2/team/get_info \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d null
```

The `team_id` field in the response is the value to enter in Teleskope.

## Enroll the Dropbox Connector

{% stepper %}
{% step %}

### Open Dropbox settings

1. In Teleskope, go to **Settings → Connectors**.
2. Select **Dropbox** from the connectors list.
3. Click **Enroll**.
   {% endstep %}

{% step %}

### Enter your credentials

On the enrollment page, fill in:

1. **Instance name** — A short identifier for this team (letters, numbers, `- _ . @`). It appears in the Data Catalog as the connector instance.
2. **Team ID** — Your Dropbox team ID (`dbtid:...`)
3. **App key** and **App secret** — From the app's **Settings** tab
4. **Refresh token** — From the token exchange above
5. **Admin team member ID** *(optional)* — A specific team admin for Teleskope to act as. When left blank, Teleskope selects an active team admin automatically.

Click **Enroll**.
{% endstep %}

{% step %}

### Confirm verification

Teleskope verifies the credentials against Dropbox immediately: it confirms the team ID matches, records the team name, and checks that the team has a team space.

* **Verified** — the Dropbox instance appears in the enrolled list and crawling is scheduled.
* **Stored, not yet verified** — the credentials were saved but Dropbox could not be reached or rejected them. Fix the cause and click **Verify** on the Dropbox settings page. Crawling does not start until verification succeeds.
* **No team space** — the team uses a legacy configuration that Teleskope does not scan. The enrollment is recorded but will not be crawled.
  {% endstep %}
  {% endstepper %}

## What Teleskope Scans

Each enrolled team appears in the Data Catalog with one data store per **team folder** and one per **member folder**.

| Content                                         | Behavior                                                                                                                                                                                                                         |
| ----------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Files in team folders and member folders        | Cataloged and classified. Incremental crawls pick up changes since the previous run.                                                                                                                                             |
| Dropbox Paper, Google-format, M365-format files | Listed in the catalog but **not downloaded or classified**. These require an export step that is not part of the connector. They are counted as skipped.                                                                         |
| Folder and file membership                      | Recorded as access, with each member classified as internal or external by email domain.                                                                                                                                         |
| Shared links                                    | Collected per team member. Each link is recorded with its **resolved** audience — the audience Dropbox actually enforces after team and folder policies are applied, which may be narrower than what the link creator requested. |

### Shared link access

A file's **Shared Link Access** is the most permissive link that reaches it, whether that link is on the file itself or on any parent folder. Audiences, from most to least permissive: `public`, `password`, `team_and_password`, `team_only`, `shared_folder_only`, `no_one`, `only_you`. The file detail page shows the link and the folder it was inherited from.

Link discovery runs once per team member. If a member's sweep does not complete, the run's link results are held as **incomplete** rather than shown as "no links" — an empty result is never treated as proof that no link exists.

## Managing the Enrollment

From **Settings → Connectors → Dropbox** you can:

* **Verify** — re-run the enrollment check against Dropbox.
* **Edit credentials** — rotate the app key, secret, or refresh token.
* **Disable / Enable** — pause and resume crawling without removing catalog data.
* **Delete** — remove the enrollment. Cataloged data is retained but no longer refreshed.

## Troubleshooting

| Symptom                                           | Cause and fix                                                                                                        |
| ------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| `invalid_client` on enrollment                    | App key or secret is wrong. Copy both from the app's **Settings** tab.                                               |
| `invalid_grant` on enrollment                     | The refresh token was revoked or issued for a different app. Regenerate it.                                          |
| Verified, but a scope error appears in crawl logs | A scope was added after the token was issued. Enable all scopes, click **Submit**, and regenerate the refresh token. |
| Team has no team space                            | Legacy Dropbox team configuration. Contact Dropbox support to migrate to the team space, then click **Verify**.      |
| Files show as skipped                             | Paper, Google-format, and M365-format files are not classified. See [What Teleskope Scans](#what-teleskope-scans).   |