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

# Gmail OAuth

> Set up Gmail OAuth for the connector

This section walks through setting up the Gmail connector using a OAuth-enabled Google App.
Anyone can do this (even without a paid Google Workspace)!

If you're an organization with a Google Workspace, and you'd rather use a Service Account to access Gmail,
checkout the section [here](./service_account).

### Authorization

<Steps>
  <Step title="Create Google Cloud Project">
    * [https://console.cloud.google.com/projectcreate](https://console.cloud.google.com/projectcreate)
  </Step>

  <Step title="Enable Gmail API">
    * On the left panel, open **APIs & services**
    * Go to **Enabled APIs and services**
    * On the top click **+ENABLE APIS AND SERVICES**
    * Search for **Gmail API** and click **ENABLE**
    * Alternatively visit this [link](https://console.cloud.google.com/apis/enableflow?apiid=gmail.googleapis.com), select your project and enable the **Gmail API**
  </Step>

  <Step title="Set up OAuth consent screen">
    * Under **APIs & services**, select the **OAuth consent screen** tab
    * If you don't have a **Google Organization** select **External** for **User Type**
    * Call the app Hymalaia (or whatever you want)
    * For the required emails, use any email of your choice or `support@hymalaia.com` if you wish for the Hymalaia team to help handle issues.
    * Click **SAVE AND CONTINUE**
  </Step>

  <Step title="Set up scopes">
    * Add the scope `.../auth/gmail.readonly` for `Gmail API`

    <Info>
      To enable permission syncing for this connector:

      * Enable the **Admin SDK API** (visit this link: [https://console.cloud.google.com/flows/enableapi?apiid=admin.googleapis.com](https://console.cloud.google.com/flows/enableapi?apiid=admin.googleapis.com)) and enable it for your project.
      * Add the scope `.../auth/admins.directory.user.readonly` for `Admin SDK API`.
      * Add the scope `.../auth/admins.directory.group.readonly` for `Admin SDK API`.
      * The account performing the OAuth flow must have an Admin role in the Google Workspace that
        has access to the "Groups > Read" privilege.
        This can be set in the Google Admin Console under Account > Admin roles.
    </Info>

    <img className="rounded-xl shadow-md mx-auto" src="https://mintcdn.com/hymalaia/L7O3OuitqD-U7MiJ/images/connectors/gmail/GmailScopes.png?fit=max&auto=format&n=L7O3OuitqD-U7MiJ&q=85&s=0c39b70e4fa10b876c3d74875a829a7f" alt="Google Cloud OAuth consent screen with Gmail readonly scope selected" width="1028" height="260" data-path="images/connectors/gmail/GmailScopes.png" />
  </Step>

  <Step title="Set up test users">
    * This is only applicable for users without a Google Organization.
    * Add at least one test user email.
      Only the email accounts added here will be allowed to run the OAuth flow to index new emails.
    * Click **SAVE AND CONTINUE**, review the changes and click **BACK TO DASHBOARD**
  </Step>

  <Step title="Create OAuth credentials">
    * Go to the **Credentials** tab and select **+ CREATE CREDENTIALS** -> **OAuth client ID**

    <img className="rounded-xl shadow-md mx-auto" src="https://mintcdn.com/hymalaia/L7O3OuitqD-U7MiJ/images/connectors/google_drive/GoogleDriveCredential.png?fit=max&auto=format&n=L7O3OuitqD-U7MiJ&q=85&s=969b43a550e41c39a2ea9e40cc4adaff" alt="Creating OAuth client ID in Google Cloud Console for Gmail" width="2996" height="1720" data-path="images/connectors/google_drive/GoogleDriveCredential.png" />

    * Choose **Web application** and give it some name like `HymalaiaConnector`
    * Add an **Authorized JavaScript origins**
    * `http://localhost:3000` if self-hosting
    * `https://<INTERNAL_DEPLOYMENT_URL>` if you have setup Hymalaia for production use
    * Add an **Authorized redirect URIs**
    * `http://localhost:3000/admin/connectors/gmail/auth/callback` if self-hosting
    * `https://<INTERNAL_DEPLOYMENT_URL>/admin/connectors/gmail/auth/callback` if you have setup Hymalaia for production use

    <img className="rounded-xl shadow-md mx-auto" src="https://mintcdn.com/hymalaia/L7O3OuitqD-U7MiJ/images/connectors/gmail/GmailCredentials.png?fit=max&auto=format&n=L7O3OuitqD-U7MiJ&q=85&s=178a0a63def97b3f14dea39c88a65c59" alt="Authorized origins and redirect URIs for Gmail OAuth client" width="1108" height="1546" data-path="images/connectors/gmail/GmailCredentials.png" />

    * Click create and on the right hand side next to **Client secret**,
      there is an option to download the credentials as a JSON. Download the JSON for use in the next step.

    <img className="rounded-xl shadow-md mx-auto" src="https://mintcdn.com/hymalaia/L7O3OuitqD-U7MiJ/images/connectors/google_drive/DriveDownloadCredentials.png?fit=max&auto=format&n=L7O3OuitqD-U7MiJ&q=85&s=36e227517b97a3f8b9cb6f9d2e6dcfd4" alt="Download OAuth client JSON credentials from Google Cloud Console" width="638" height="684" data-path="images/connectors/google_drive/DriveDownloadCredentials.png" />
  </Step>
</Steps>

### Indexing

First, navigate to the Admin Panel and select the Gmail connector.

Then, click **Create New**. Under **Option 1: OAuth app**, upload (or paste) the OAuth app JSON you downloaded above,
then click **Authenticate with Gmail**, then continue with the account you want to use to index Gmail.

Once complete, select the newly created credential, and click the **Continue** button to configure the connector!

<Note>
  The app JSON is stored on the credential it creates, so each OAuth credential carries its own app.
  To add more connectors for the same account,
  select the existing credential from the list instead of creating a new one.
  An instance can hold multiple Gmail credentials.
</Note>

### Using one credential for Gmail and Google Drive

A Google credential created in Hymalaia is listed on both the Gmail and the Google Drive connector forms,
so one account can index both. For this reason, the Google consent screen asks for the scopes of both connectors:

| Connector | Scopes |
| - | - |
| Google Drive | `drive.readonly`, `drive.metadata.readonly`, `admin.directory.user.readonly`, `admin.directory.group.readonly` |
| Gmail | `gmail.readonly`, `admin.directory.user.readonly`, `admin.directory.group.readonly` |

* To use the credential for both connectors, grant every scope on the consent screen.
  Add the scopes of both connectors to your app's OAuth consent screen,
  and add the redirect URI of each connector form you authenticate from.
* To use the credential for one connector only, untick the scopes of the other connector on the consent screen.
  The credential then works only for the connector whose scopes you granted.
  The connector checks report the missing scopes if you select it for the other connector.

To add the other connector's scopes later, authenticate the credential again and grant them.


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