> ## Documentation Index
> Fetch the complete documentation index at: https://docs.onyx.app/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,
it will be available soon!

### 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 Onyx (or whatever you want)
    * For the required emails, use any email of your choice or `founders@onyx.app` if you wish for the Onyx 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.
      * Note: Service Account support for Gmail is in development and will be available soon.
    </Info>

    <img className="rounded-image" src="https://mintcdn.com/danswer/24Ocig51qMqahMaT/assets/admins/connectors/gmail/GmailScopes.png?fit=max&auto=format&n=24Ocig51qMqahMaT&q=85&s=7558c21397fc52689a3e7724684488df" alt="Google Cloud OAuth consent screen with Gmail readonly scope selected" width="1028" height="260" data-path="assets/admins/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-image" src="https://mintcdn.com/danswer/24Ocig51qMqahMaT/assets/admins/connectors/google_drive/GoogleDriveCredential.png?fit=max&auto=format&n=24Ocig51qMqahMaT&q=85&s=cf21e78b5a2b257a1f1befa44c7f6555" alt="Creating OAuth client ID in Google Cloud Console for Gmail" width="2996" height="1720" data-path="assets/admins/connectors/google_drive/GoogleDriveCredential.png" />

    * Choose **Web application** and give it some name like `OnyxConnector`
    * Add an **Authorized JavaScript origins**
    * `http://localhost:3000` if self-hosting
    * `https://<INTERNAL_DEPLOYMENT_URL>` if you have setup Onyx for production use
    * `https://cloud.onyx.app` if you are using the Onyx Cloud service
    * 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 Onyx for production use
    * `https://cloud.onyx.app/admin/connectors/gmail/auth/callback` if you are using the Onyx Cloud service

    <img className="rounded-image" src="https://mintcdn.com/danswer/24Ocig51qMqahMaT/assets/admins/connectors/gmail/GmailCredentials.png?fit=max&auto=format&n=24Ocig51qMqahMaT&q=85&s=bb6133033a435ab855b4f377a12e9dc0" alt="Authorized origins and redirect URIs for Gmail OAuth client" width="1108" height="1546" data-path="assets/admins/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-image" src="https://mintcdn.com/danswer/24Ocig51qMqahMaT/assets/admins/connectors/google_drive/DriveDownloadCredentials.png?fit=max&auto=format&n=24Ocig51qMqahMaT&q=85&s=f8368e43322887e6e63ae4c3bffc1375" alt="Download OAuth client JSON credentials from Google Cloud Console" width="638" height="684" data-path="assets/admins/connectors/google_drive/DriveDownloadCredentials.png" />
  </Step>
</Steps>