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

# Dropbox Connector

> Search, read, and analyze files and folders in your Dropbox account or team from Ana.

### **1. Overview**

The Ana x Dropbox integration connects your Dropbox account or team to Ana, giving you natural language access to your files. Once configured, Ana can list folders, search by name, read document content, and report on sharing activity without leaving your workflow.

<Note>
  Connect Dropbox to Ana to search, read, and analyze the files and folders you have access to using natural language.
</Note>

### **2. Prerequisites**

You'll need:

* A Dropbox account (personal or Dropbox Business) with the files you want Ana to query
* Access to the [Dropbox App Console](https://www.dropbox.com/developers/apps) to create an app
* A TextQL account with permission to add API connectors

### Which type of connection should I use?

|                     | **Access Token**                                                                         | **OAuth (Org-level)**                          | OAuth (Per-member)                               |
| ------------------- | ---------------------------------------------------------------------------------------- | ---------------------------------------------- | ------------------------------------------------ |
| **Best For**        | Quick tests                                                                              | Shared team access to one Dropbox account      | Individual user access with personal permissions |
| **Scope**           | The app's enabled permissions                                                            | Full access under one shared authorization     | Each user queries Dropbox as themselves          |
| **Authentication**  | Token generated in the App Console                                                       | One-time OAuth flow by an admin                | Each member completes their own OAuth flow       |
| **Data Visibility** | Whatever the token's account can see                                                     | Consistent view across all Ana users           | Each user sees only what they can see in Dropbox |
| **Limitations**     | Tokens generated in the App Console expire after 4 hours and must be regenerated by hand | Requires admin to re-auth if access is revoked | Higher setup overhead; each member must connect  |

<Warning>
  Dropbox no longer issues long-lived access tokens. A token generated in the App Console stops working after 4 hours. Use OAuth for anything beyond a quick test: TextQL stores the refresh token and renews access automatically.
</Warning>

### **3. Capabilities**

Once configured, Ana can:

* List and search files and folders across your account or team space.
* Read the content of documents, spreadsheets, and text files.
* Report on file metadata such as size, owner, and last modified date.
* Surface shared links and shared folder membership.

### **4. Setup Instructions**

***

### Step 1: Create a Dropbox app

Both connection types use a Dropbox app. The app defines which permissions (scopes) Ana can use.

1. Go to the [Dropbox App Console](https://www.dropbox.com/developers/apps) and click **Create app**.
2. Choose **Scoped access**.
3. Choose the access type: **Full Dropbox** to let Ana read your existing files, or **App folder** to restrict it to one new folder.
4. Name the app (for example `textql-ana`) and click **Create app**.
5. Open the **Permissions** tab and enable at least:
   * `account_info.read`
   * `files.metadata.read`
   * `files.content.read`
   * `sharing.read`
6. If a **Submit** button appears at the bottom of the Permissions tab, click it.

<Warning>
  Do this before you generate a token or authorize. Dropbox stamps each access token with the permissions the app had at that moment. A permission you enable later is not added to existing tokens. After any change on the Permissions tab, generate a new access token, or remove and re-authorize the OAuth connection.
</Warning>

<Tabs>
  <Tab title="Access Token">
    1. On the app's **Settings** tab, scroll to **OAuth 2** and click **Generate** under **Generated access token**.
    2. Copy the token immediately. It expires 4 hours after it is generated.
    3. Generate a new token any time you change the app's permissions. The old token keeps the old permissions.

    For the latest steps, see Dropbox's [OAuth guide](https://developers.dropbox.com/oauth-guide).
  </Tab>

  <Tab title="OAuth (Org-level or Per-member)">
    1. On the app's **Settings** tab, scroll to **OAuth 2**.
    2. Under **Redirect URIs**, add `https://app.textql.com/auth/api-oauth/callback` and click **Add**.
    3. Copy the **App key** (this is your Client ID) and click **Show** next to **App secret** to copy the Client Secret.

    <Tip>
      The difference between org-level and per-member connections is determined by how TextQL manages authentication:

      * **Org-level connection**: one member authorizes Dropbox once, and TextQL stores a shared token for that organization.
      * **Per-member connection**: each user in TextQL completes OAuth individually, and TextQL stores separate tokens per user, preserving identity and permissions.

      Both use the same Dropbox app. Only the authorization behavior and token storage differ.
    </Tip>
  </Tab>
</Tabs>

### **Step 2: Add Dropbox as an API connector in TextQL**

1. Go to app.textql.com and sign in.
2. In the bottom left sidebar, click **Connectors > APIs** and select Dropbox.
3. In the configuration panel, fill in the fields depending on your connection type:
   * **Access Token**
     * Name (e.g. Dropbox `Access Token`)
     * Authentication type: select **API Key**
     * Token: paste the generated access token from Step 1
   * **OAuth (Org-level or Per-member)**
     * Name (e.g. Dropbox `OAuth`)
     * Authentication type: select **OAuth (org-level)** or **OAuth (per-member)**
     * Client ID and Client Secret: paste the App key and App secret from Step 1
     * Scopes: leave the defaults unless you enabled additional permissions on the app
     * OAuth Authentication: click **Authenticate**. A popup asks for permission to access your Dropbox. Click **Allow**.
4. Click **Save**.

### **Step 3: Verify the connection**

Once saved, confirm the connector is active:

1. Click on the Dropbox connector and select Test Connection at the bottom of the panel.

* A successful setup will return Connection successful (200) with your account details.
* If the test fails, refer to the [Troubleshooting](#6-troubleshooting) section for next steps.

2. Ask Ana to list a folder, for example "What is in the root of my Dropbox?"

* The test only checks that the token is valid. It passes with `account_info.read` alone, so it cannot tell you whether the file permissions are on the token. Listing a folder does.

***

### **5. Usage Examples**

Once configured, you can ask Ana:

* "List everything in the `Board Decks` folder, newest first."
* "Find every spreadsheet modified in the last 7 days and summarize what changed."
* "Read the Q3 planning doc in `Finance/2026` and pull out the headcount assumptions."
* "Which folders are shared outside the team, and with whom?"
* "How much storage is each top-level folder using?"

### **6. Troubleshooting**

| **Symptom**                                                                                             | **Likely Cause**                                                                                                                                                           | **Fix**                                                                                                                        |
| ------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| Test fails with `expired_access_token`                                                                  | Generated access tokens expire after 4 hours                                                                                                                               | Switch to OAuth, or generate a new token in the App Console and update the connector.                                          |
| Authentication failed (OAuth)                                                                           | Redirect URI not registered on the app                                                                                                                                     | In the App Console, make sure `https://app.textql.com/auth/api-oauth/callback` is listed exactly under **Redirect URIs**.      |
| OAuth popup shows `invalid_scope`                                                                       | The connector requests a permission the app does not have                                                                                                                  | Enable the missing permission on the app's **Permissions** tab and click **Submit**, then authenticate again.                  |
| Test Connection passes but Ana gets `400` with "does not have the required scope 'files.metadata.read'" | The token was generated before the permission was enabled. Dropbox does not add new permissions to existing tokens, and the connection test only needs `account_info.read` | Generate a new access token in the App Console and update the connector. For OAuth, remove the connection and authorize again. |
| Permissions are ticked in the App Console but the error persists                                        | Same cause: the token predates the change                                                                                                                                  | Regenerate the token. Ticking a box never updates a token that already exists.                                                 |
| Ana can list files but not read them                                                                    | `files.content.read` was not on the token                                                                                                                                  | Enable it on the Permissions tab, then generate a new token or re-authenticate so the new scope is granted.                    |
| OAuth connection stops working after a few hours                                                        | The app was authorized before the connector requested offline access                                                                                                       | Remove the connector's token and authenticate again.                                                                           |

### **7. Security Notes**

* Follow the principle of least privilege. Enable only the read permissions Ana needs, and prefer **App folder** access when Ana only needs a subset of your files.
* OAuth refresh tokens remain valid until the user revokes the app under Dropbox **Settings > Connected apps**. Revoke it there if you suspect exposure.
* Do not share access tokens, app secrets, or OAuth credentials in email, chat, tickets, or other unsecured locations.
* If you no longer need the integration, revoke the app in Dropbox and remove the connector from TextQL.
* For more details on how Dropbox handles authentication and permissions, refer to [Dropbox's HTTP API documentation](https://www.dropbox.com/developers/documentation/http/documentation).

***

### **Need Help?**

For further assistance, please contact [support@textql.com](mailto:support@textql.com).

### **Privacy Policy**

For information about how we handle your data and protect your privacy, please review our [Privacy Policy](https://textql.com/privacy).