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

# Google Drive

# Set Up the Google Drive Connector

The Google Drive Connector allows you to ingest personal and shared files from your Google Drive into your project. You can authenticate in one of two ways:

* **Airia-managed OAuth** — Use Airia's built-in Google application. No Google Cloud setup is required. This option supports the `drive.file` scope only, so you select **individual files** through the Google Native File Picker.
* **Bring Your Own OAuth (BYOO)** — Register your organization's own Google OAuth application. This gives you full control over the consent screen and the permissions requested, and it lets you offer the `drive.readonly` scope for **folder-level and shared-drive** access through the Airia Folder Picker.

The scope on the credential you authenticate with determines how you select files — see [File Picker Modes](#file-picker-modes) below.

> 💡 Tip: To use **Airia-managed OAuth**, skip ahead to [Create a Google Drive Data Source](#create-a-google-drive-data-source) and select **Airia-managed OAuth** as the connector. To use **BYOO**, complete the OAuth app setup below first.

## Set Up Your Google OAuth App

> 💡 Note: This section applies only if you are using **Bring Your Own OAuth**. If you are using **Airia-managed OAuth**, skip to [Create a Google Drive Data Source](#create-a-google-drive-data-source).

This one-time setup registers your organization's OAuth application in Google Cloud Console so Airia can access Google Drive on your users' behalf.

> 💡 Tip: For a full walkthrough with screenshots, see [Setting Up Google Cloud Console OAuth App](https://explore.airia.com/integrations/oauth-setup/google-cloud-console). The steps below cover what is specific to the Google Drive data source.

### 1. Get the Redirect URL from Airia

Before creating the app in Google, copy the redirect URL that Airia will use for the OAuth callback:

1. In the Airia platform, navigate to **Settings** > **Ecosystem** > **App connections**.
2. Select the **Available** tab and click **Google**.
3. Copy the **Redirect URL** displayed on the form (for example, `https://auth.airia.ai/OAuth/callback`).

> ⚠️ Warning: The redirect URL is case-sensitive and must be pasted into Google Cloud Console exactly as shown. A mismatch causes a `redirect_uri_mismatch` error during authentication.

### 2. Create or Select a Google Cloud Project

1. Go to the [Google Cloud Console](https://console.cloud.google.com/).
2. Create a new project or select an existing one.

### 3. Enable the Google Drive API

1. Navigate to **APIs & Services** > **Library**.
2. Search for **Google Drive API**.
3. Click **Enable**.

### 4. Configure the OAuth Consent Screen

1. Navigate to **APIs & Services** > **OAuth consent screen**.
2. Select a **User Type**:
   * **Internal** — Only users within your Google Workspace organization can authenticate. Simpler setup; no Google verification required.
   * **External** — Any Google account can authenticate. Requires publishing the app and, for sensitive scopes, going through Google's verification process.
3. Fill in the required fields: **App name**, **User support email**, and **Developer contact email**.
4. Under **Scopes**, add the scopes you intend to support (see [OAuth Scopes](#oauth-scopes)).
5. If you selected **External** and the app is still in testing, add the emails of users who will authenticate under **Test users**.

> ⚠️ Warning: External apps that request `drive.readonly` may require Google's app verification before users outside your organization can authenticate. This can take days to weeks. Until verification completes, only listed test users can authenticate.

### 5. Create OAuth 2.0 Credentials

1. Navigate to **APIs & Services** > **Credentials**.
2. Click **Create Credentials** > **OAuth client ID**.
3. Set **Application type** to **Web application**.
4. Under **Authorized redirect URIs**, paste the Redirect URL you copied from Airia in Step 1.
5. Click **Create**.
6. Copy the **Client ID** and **Client Secret** — you will need these in the next section.

## Register the OAuth Connector in Airia

1. In the Airia platform, navigate to **Settings** > **Ecosystem** > **App connections**.
2. Select the **Available** tab and click **Google**.
3. Enter the following details:
   * **Name**: A descriptive name to identify this connector (e.g., `Company Google Drive`).
   * **Client ID**: The Client ID from Google Cloud Console.
   * **Client Secret**: The Client Secret from Google Cloud Console.
   * **Scopes**: Add the scopes this connector should support (see [OAuth Scopes](#oauth-scopes)).
4. Click **Create**.

> 💡 Note: The scopes you add here define what users can request when they create a credential. To let users browse folders and shared drives, you **must** include `https://www.googleapis.com/auth/drive.readonly`. If you omit it, users are limited to `drive.file` and the Google Native File Picker. See [File Picker Modes](#file-picker-modes).

## Create a Google Drive Data Source

### 1. Add a New Google Drive Data Source

1. In the Airia platform, navigate to **Available data sources**.
2. Select the **Google Drive** card.

### 2. Configure Data Source Details

1. Provide the following details:
   * **Name**: A mandatory, descriptive name for your data source.
   * **Description**: (Optional) A brief description.
   * **Scope**: Select the Airia project for this data source.
   * **OAuth connector**: From the dropdown, select **Airia-managed OAuth**, or the Google OAuth connector you registered above (BYOO).
2. For **Credentials**, choose `Create new credential`.
3. Enter a **Name** for the new credential.
4. Confirm the scopes to request for the authenticating user. The scope you select here determines your file selection mode and **cannot be changed later** without creating a new credential.
5. Enable **Permission check** if access control is required for the files in this data source (see [Enforce Permissions](#enforce-permissions-for-google-drive-data-sources)).
6. Click **Authenticate**. Complete the Google OAuth flow by signing in with an account that has access to the files you want to ingest.

### 3. Select Content and Start Ingestion

After you authenticate, Airia opens the file selector that matches your credential's scope (see [File Picker Modes](#file-picker-modes)). Browse and select the content you want to ingest, then click **Done** to create the data source and start ingestion.

You can view the current ingestion status by opening the data source. The detailed list shows all ingested files and their status.

> 💡 Note: To edit your content selection, open the data source and click **Edit**. You may need to reauthenticate. If you reauthenticate with different user credentials, the selector will not show previous selections and you will need to reselect all items.

## File Picker Modes

Airia chooses the file selection UI automatically, based on the OAuth scope on the credential you authenticate with. There is no separate setting for it.

| Scope on Credential | File Selection Mode           | What You Can Select                                                                                |
| ------------------- | ----------------------------- | -------------------------------------------------------------------------------------------------- |
| `drive.file`        | **Google Native File Picker** | Only the individual files you explicitly pick through Google's own picker UI.                      |
| `drive.readonly`    | **Airia Folder Picker**       | Any folder in your Drive, including shared drives — full read-only browse of the folder hierarchy. |

> 💡 Note: **Airia-managed OAuth** supports the `drive.file` scope only, so it always uses the Google Native File Picker. To use the Airia Folder Picker (folders and shared drives), authenticate with a **BYOO** connector that offers the `drive.readonly` scope.

When using the **Google Native File Picker** (`drive.file`):

> 💡 Note:
>
> * You can select files only within one folder at a time.
> * If you select files from multiple folders in one pass, **only the files from the last folder selected will be synced.**
> * To ingest files from multiple folders: select files from `folder1` and click **Select**, then reopen the picker and select files from `folder2`.

When using the **Airia Folder Picker** (`drive.readonly`), selecting a folder syncs all supported content within it, including subfolders and their contents. Shared drives are available for selection.

> 💡 Tip: Reprocessing the data source automatically syncs newly added content, updates modified content, and removes deleted items within your selection.

## OAuth Scopes

The scopes configured on the OAuth connector define which scopes users can request when they create a credential. The scope chosen at credential creation determines the file picker mode and cannot be changed without creating a new credential.

| Scope                                            | Purpose                                                                                                                                     |
| ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `https://www.googleapis.com/auth/userinfo.email` | Read the user's email address.                                                                                                              |
| `https://www.googleapis.com/auth/drive.file`     | Access only the files the user selects through the Google Native File Picker.                                                               |
| `https://www.googleapis.com/auth/drive.readonly` | Read-only access to all files in Drive, including shared drives. Required for the Airia Folder Picker. Available with BYOO connectors only. |

## Enforce Permissions for Google Drive Data Sources

Airia filters Google Drive query results based on the end-user's access permissions to the files.

### Prerequisites

To enable permission enforcement for your Google Drive data source:

* **Single Sign-On (SSO)** must be enabled for your Airia project.
* **Permission check** must be enabled when configuring the data source.
* For Google Drive, only users who have edit access to the files will be able to view files or retrieve any content from them.
* For more information on how permissions work, see [Permissions Enforcement Overview](https://explore.airia.com/integrations/Data-Source-Connectors/Permissions%20Enforcement).

> ⚠️ Warning:
> For Google Drive, platform users' UI access to file details depends on their original file permissions:
>
> * Users with **edit access** to the original Google Drive files can view the file names and their content (SQL table, chunks, Binder) within the platform UI.
> * Users without **edit access** to the original Google Drive files will see file names redacted and cannot view file content in the platform UI.

## Migrate Existing Data Sources from the Legacy Authentication Flow

Google Drive data sources created with the legacy authentication flow (Google username and password) must be updated to use OAuth. An administrator updates each existing data source once:

1. Open the data source and click **Edit**.
2. Select the **OAuth provider** — your BYOO Google OAuth connector, or Airia-managed OAuth.
3. **Create** a new OAuth credential, or **select** an existing one.
4. Complete the OAuth flow to authenticate.

### Migrating to the `drive.readonly` Scope

The legacy flow used the Google Native File Picker (individual files). If you migrate a legacy data source to a credential with the `drive.readonly` scope, the file selection mode changes to the **Airia Folder Picker**:

* The administrator must **reselect the content as folders** using the Airia Folder Picker — the previous file-level selections do not carry over.
* Because the selection changes, the data source requires a **full re-ingestion** of the newly selected content.

> 💡 Tip: If you want to preserve individual-file selections and avoid re-ingestion, migrate to a credential with the `drive.file` scope, which keeps the Google Native File Picker.

## Limitations

| Limitation                        | Details                                                                                                                            |
| --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| **Scope immutability**            | Scopes cannot be changed after a credential is created. Create a new credential to switch picker modes.                            |
| **Credentials are user-specific** | Credentials are not shared. Each user must authenticate independently through the OAuth flow.                                      |
| **Shared drive access**           | Browsing shared drives requires the `drive.readonly` scope. The `drive.file` scope does not support it.                            |
| **Google app verification**       | External-type apps that request sensitive scopes (`drive.readonly` and above) require Google's verification before production use. |
| **Test user restriction**         | Before app verification, only explicitly listed test users can authenticate through an External-type app.                          |
| **Redirect URI case-sensitivity** | The redirect URI in Google Cloud Console must exactly match the URL shown in Airia, including case.                                |

## Troubleshooting

| Symptom                                                 | Likely Cause                                                     | Resolution                                                                                                                            |
| ------------------------------------------------------- | ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `drive.readonly` not offered during credential creation | The scope is not in the OAuth connector's supported scopes       | Edit the connector under **Settings** > **Ecosystem** > **App connections** and add `https://www.googleapis.com/auth/drive.readonly`. |
| OAuth callback fails with `redirect_uri_mismatch`       | The redirect URI in Google Cloud Console does not match Airia's  | Copy the exact Redirect URL from the Airia Google connector form and paste it into Google Cloud Console.                              |
| User cannot authenticate (access denied)                | The user is not a test user on an unverified External app        | Add the user's email under **Test users** in Google Cloud Console, or complete app verification.                                      |
| Folder picker not shown when expected                   | The credential was created with `drive.file` scope               | Create a new credential using a connector that has `drive.readonly` in its supported scopes.                                          |
| Selection cleared after changing the connector          | Changing the connector resets the stale credential and selection | Reauthenticate with the new connector and reselect your files or folders.                                                             |

## Next Steps

After your data has been successfully ingested, the Google Drive data source is ready to be used with an Agent.