> ## Documentation Index
> Fetch the complete documentation index at: https://support.configview.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Dropbox setup

ConfigView reads your Dropbox team through Dropbox's Business (team) API, using a small **Dropbox app that your own team admin creates** in the Dropbox App Console and authorises once for the team. ConfigView is not a published Dropbox app; nothing is installed from a marketplace.

You will end up with **3 secrets** in ConfigView (`DROPBOX_APP_KEY`, `DROPBOX_APP_SECRET` and `DROPBOX_REFRESH_TOKEN`) when setup is complete.

> **Scope of this integration today.** ConfigView reads who is on your Dropbox team and with which admin role, your groups, the third-party apps each person has connected to their Dropbox, every computer, phone and browser signed in to each account, your team's sharing and link policies, and Dropbox's audit log: sign-ins, sharing with people outside the company, app links, device links, member and admin changes, two-step verification and policy changes. ConfigView only reads. It never opens, lists or downloads files, and it never reads file or folder names.

**Plan:** any Dropbox team plan (Standard, Advanced, Business, Business Plus, Enterprise). Personal plans (Basic, Plus, Essentials, Family) have no team API.

***

## Step 1: Open the Dropbox page in ConfigView

Open ConfigView in a second browser tab and leave it open:

`https://{companyname}.configview.com/admin/integrations/dropbox`

***

## Step 2: Create the Dropbox app

You need to be a **Team admin** in Dropbox. The app is created under your own Dropbox account and stays in Dropbox's *development* status, which is all a single team needs: there is nothing to submit to Dropbox for review.

1. Go to [dropbox.com/developers/apps](https://www.dropbox.com/developers/apps) while signed in as the team admin and click **Create app**
2. **Choose an API:** **Scoped access**
3. **Choose the type of access you need:** **Full Dropbox**. Dropbox only offers team permissions to Full Dropbox apps. ConfigView does not use any file permission
4. **Name your app:** something unique, e.g. `ConfigView - {Company}`. Click **Create app**
5. Open the **Permissions** tab. Under **Team scopes**, tick exactly these:

| Scope | What ConfigView reads with it |
| - | - |
| `team_info.read` | Licence counts, sharing and link policies, which admin authorised the app |
| `members.read` | Team members, their roles and status |
| `groups.read` | Groups and who is in them |
| `sessions.list` | Linked third-party apps, and signed-in devices and browsers |
| `events.read` | The audit log |

`account_info.read` is always ticked by Dropbox and cannot be removed; leave it. Do **not** tick any `files.*`, `sharing.*`, `team_data.*` or `*.write` scope. If Dropbox ticks a scope automatically because another one depends on it, leave it ticked.
6\. Click **Submit** at the bottom of the Permissions tab
7\. Open the **Settings** tab. Copy the **App key** into `DROPBOX_APP_KEY` in ConfigView, then click **Show** beside **App secret** and copy it into `DROPBOX_APP_SECRET`. Click the save icon

***

## Step 3: Authorise the app for your team and get a refresh token

This is a one-time step. Still signed in to Dropbox as the **team admin**:

1. Paste this address into your 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. Dropbox shows the permissions the app asks for, on behalf of your **team**. Click **Continue**, then **Allow**

3. Dropbox shows an **access code**. Copy it. The code works once and only for a few minutes, so do the next step straight away

4. Exchange the code for a refresh token. In a terminal (macOS, Linux, or Windows 10+ Command Prompt), replacing the three values:

   ```bash theme={null}
   curl https://api.dropboxapi.com/oauth2/token \
     -d code=ACCESS_CODE \
     -d grant_type=authorization_code \
     -u APP_KEY:APP_SECRET
   ```

   or in Windows PowerShell:

   ```powershell theme={null}
   Invoke-RestMethod -Method Post -Uri https://api.dropboxapi.com/oauth2/token `
     -Body @{code='ACCESS_CODE'; grant_type='authorization_code'; client_id='APP_KEY'; client_secret='APP_SECRET'}
   ```

5. The answer is a short block of JSON. Copy the value of **`refresh_token`** (not `access_token`, which starts with `sl.` and expires in four hours) into `DROPBOX_REFRESH_TOKEN` in ConfigView and click the save icon. The answer should also contain a `team_id`; if it does not, the person who clicked **Allow** was not a team admin. Start step 3 again as a team admin

The refresh token does not expire. ConfigView trades it for a short-lived access token on each run.

**If you change the ticked scopes later**, click **Submit** again and repeat this step: a refresh token keeps the permissions it was issued with.

**To revoke ConfigView's access**, delete the app in the App Console; every token it issued stops working.

***

## Step 4: Connect and verify

1. Back on `https://{companyname}.configview.com/admin/integrations/dropbox`, confirm the three credentials show as saved
2. Click **Connect**. ConfigView creates its tables and schedules every collector at your default run time. Stop any you don't want under **Collectors**:

| Script | Notes |
| - | - |
| **Team & Sharing Policies** | The team's licence count and its sharing rules: who can see shared links by default, whether outsiders can join shared folders, link passwords and expiry, who can create groups, and which admin authorised ConfigView. |
| **Members** | Every Dropbox team member, including suspended, invited and removed ones: name, email, admin role, status, licence type, groups, and when they were invited, joined or suspended. |
| **Groups** | The team's Dropbox groups: name, how many members, and whether admins, members or Dropbox manage them. |
| **Group Members** | Who is in each Dropbox group, and who manages it. Runs after Groups. |
| **Linked Apps** | Every third-party app each member has connected to their Dropbox, when it was connected, who publishes it, and whether it can see the whole Dropbox or only its own folder. Runs after Members. |
| **Devices & Sessions** | Every web session, desktop app and mobile app signed in to each member's Dropbox: device name, client and version, operating system, IP address and country of last activity, and when it was first and last used. Runs after Members. |
| **Team Events (Audit Log)** | Dropbox's audit log, kept as a growing history: sign-ins and failed sign-ins, sharing with people outside the company, apps linked and unlinked, devices, member and admin-role changes, two-step verification and policy changes. File activity is not collected, and file names and links are removed. |

3. Click **Verify now**. The health check confirms the three secrets, trades the refresh token for an access token, shows which admin authorised it, then makes one small read with each of the five scopes.

If a check fails:

* **"Dropbox refused the refresh token".** The token was revoked, the app was deleted, or `DROPBOX_APP_KEY` / `DROPBOX_APP_SECRET` belong to a different app. Check the key and secret on the app's Settings tab, then repeat step 3.
* **"needs the '…' scope".** That scope was not ticked when the refresh token was made. Tick it, click **Submit**, and repeat step 3.
* **"this is a user token, not a team token".** Whoever clicked **Allow** was not a team admin, or no team scope was ticked. Repeat step 3 as a team admin.
* **Audit log shows `skip`.** Your plan or settings do not let the API read the audit log. Everything else still works; the audit table stays empty.

***

## Data Tables

Once the scripts run, these tables are created in your database. Each includes a `run_at` column. Every table keeps only the newest run, except the audit log, which keeps everything it has ever collected.

| Table | Source | Key Columns |
| - | - | - |
| `dropbox_team` | `team/get_info`, `team/features/get_values`, `team/token/get_authenticated_admin` | team\_id, name, num\_licensed\_users, num\_provisioned\_users, num\_used\_licenses, shared\_folder\_member\_policy, shared\_folder\_join\_policy, shared\_link\_create\_policy, shared\_folder\_link\_restriction\_policy, enforce\_link\_password\_policy, default\_link\_expiration\_days\_policy, shared\_link\_default\_permissions\_policy, group\_creation\_policy, emm\_state, office\_addin\_policy, suggest\_members\_policy, top\_level\_content\_policy, has\_team\_shared\_dropbox, has\_team\_file\_events, has\_team\_selective\_sync, authorized\_by\_email, authorized\_by\_team\_member\_id, policies\_json |
| `dropbox_members` | `team/members/list_v2` | team\_member\_id, account\_id, external\_id, persistent\_id, email, email\_verified, secondary\_emails, display\_name, given\_name, surname, status, removed\_recoverable, membership\_type, invited\_on, joined\_on, suspended\_on, is\_directory\_restricted, roles, role\_ids, is\_admin, group\_ids, group\_count |
| `dropbox_groups` | `team/groups/list` | group\_id, group\_name, group\_external\_id, member\_count, group\_management\_type |
| `dropbox_group_members` | `team/groups/members/list` | group\_id, group\_name, team\_member\_id, member\_email, member\_status, access\_type |
| `dropbox_linked_apps` | `team/linked_apps/list_members_linked_apps` | team\_member\_id, member\_email, member\_status, app\_id, app\_name, publisher, publisher\_host, linked, is\_app\_folder |
| `dropbox_devices` | `team/devices/list_members_devices` | team\_member\_id, member\_email, member\_status, session\_type, session\_id, device\_name, client\_type, client\_version, platform, os\_version, browser, ip\_address, country, created, updated, expires, is\_delete\_on\_unlink\_supported |
| `dropbox_team_events` | `team_log/get_events` | event\_hash, event\_time, event\_category, event\_type, event\_type\_description, actor\_type, actor\_kind, actor\_email, actor\_name, actor\_team\_member\_id, context\_type, context\_email, context\_team\_member\_id, involve\_non\_team\_member, participant\_emails, participant\_groups, external\_recipient\_emails, app\_id, app\_name, access\_method, ip\_address, city, region, country, asset\_count, asset\_types, details |
| `dropbox_team_event_sync` | (ConfigView) | category, complete\_through, last\_run\_at, last\_status, last\_rows, last\_calls, message |

**`status`** is `active`, `invited`, `suspended` or `removed`. Suspended members can be restored with everything they had, including admin roles. **`roles`** lists admin roles by name (`Team admin`, `User management admin`, `Support admin`, `Billing admin`, …); `is_admin` is 1 when someone holds any of them.

**`is_app_folder`** is 1 when a linked app can only see its own folder in that person's Dropbox, and 0 when it can read and write everything they can.

**`session_type`** is `web` (a browser session), `desktop` (the Dropbox desktop app; `device_name` is the computer's name) or `mobile` (the phone or tablet app).

**`event_category`** and **`event_type`** are Dropbox's own names, e.g. `logins` / `login_success`, `sharing` / `shared_content_add_invitees`, `apps` / `app_link_team`, `tfa` / `tfa_change_status`. `external_recipient_emails` lists outside addresses something was shared with. `details` holds the rest of the event as JSON, with Dropbox's `{".tag": …}` values kept as they are.

***

## Things worth knowing

**Apps linked to the whole team are not in `dropbox_linked_apps`.** Dropbox lists those separately from the apps people link to their own accounts. ConfigView reads them from the audit log (`app_link_team` / `app_unlink_team` events); the ConfigView app itself is one of them.

**There is no "has two-step verification" field.** Dropbox's API does not report each member's current two-step setting. ConfigView reads the history of two-step changes from the audit log instead, the full history Dropbox still holds on the first run. Someone who turned it on before that history begins shows as "no record"; check them in the Admin console.

**The first audit-log run is a backfill.** It reads every two-step verification, policy and app event Dropbox still holds, and the last **90 days** of the other categories, a week at a time. It stops starting new pages after 25 minutes and the next run carries on from where it got to (`dropbox_team_event_sync.complete_through`).

**Dropbox gives audit events no id.** ConfigView builds one (`event_hash`) from the whole event, so re-reading the same hour never creates duplicates.

**If the admin who authorised the app leaves.** The token belongs to the team, but `authorized_by_email` in `dropbox_team` shows whose consent it rests on. If that person is removed or loses the Team admin role, repeat step 3 as another team admin.

**Rate limits.** Dropbox publishes no numeric API limit. ConfigView paces itself (one call a second; two for the audit log) and waits as long as Dropbox asks when it answers 429.

## What isn't collected

* Files, folders and Paper documents: no contents, no names, no paths. ConfigView holds no file permission
* File operations, Paper, comments, file requests, Showcase and Dropbox Sign events from the audit log
* Shared-link URLs, file and folder names, and paths inside audit events. Keys that hold them are removed from `details` before it is stored; the files an event touched are kept only as a count and a kind (`asset_count`, `asset_types`)
* Profile photo URLs, browser user-agent strings and mobile carriers
* The app secret and tokens never leave Secret Manager; they are not written to any table


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.