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

# Google Workspace Apps: OAuth Setup for Admins

> Set up one Google OAuth client for Gmail, Drive, Calendar, Docs, Sheets, and every other Google app in OneCLI. Enable the APIs, choose the audience, create the client, and connect.

One Google OAuth client covers **every Google app** in OneCLI: Gmail, Calendar, Drive, Docs, Sheets, Slides, Forms, Meet, Tasks, Contacts, Chat, Photos, Admin, Analytics, Search Console, Classroom, and YouTube. Set it up once.

<Note>
  On OneCLI Cloud, Google apps work out of the box. Follow this guide only if you want your own Google client, for example to show your company name on the consent screen or to keep tokens in your own Google Cloud project. Self-hosted instances need this guide unless `GOOGLE_CLIENT_ID` and `GOOGLE_CLIENT_SECRET` are set on the server.
</Note>

## Before you start

* A Google account that can create projects in [Google Cloud console](https://console.cloud.google.com/). To keep sign-in limited to your company, use an account in your Google Workspace.
* A OneCLI **organization admin** account. Members can't change credentials.

<Note>
  Red numbers in the screenshots match the actions below each image.
</Note>

## Set up your Google client

<Steps>
  <Step title="Start in OneCLI">
    Open the credentials form for **any** Google app, for example Gmail:

    * **For the whole organization:** **Global Connections → Apps → Gmail → Custom credentials**.
    * **For one workspace only:** **Connections → Apps → Gmail → Custom credentials** in that workspace. This overrides the organization's client in that workspace.

    <Frame caption="The Google credentials form in OneCLI.">
      <img src="https://mintcdn.com/chartdbinc/uEKrweRjk4fPb19Z/images/integrations/google/01-onecli-setup.png?fit=max&auto=format&n=uEKrweRjk4fPb19Z&q=85&s=8c1525d2d09397eca7f0cc9d0c9c7dac" alt="OneCLI Google credentials form with the setup guide link, Enable the Google APIs link, Redirect URI, Client ID, Client Secret, and Save credentials." width="2210" height="1151" data-path="images/integrations/google/01-onecli-setup.png" />
    </Frame>

    * **1.** Click **Enable the Google APIs in your Cloud project**. It opens the next step.
    * **2.** Copy the **Redirect URI**. You'll paste it into Google in step 4.
    * **3.** Leave this page open. You'll paste the **Client ID** and **Client Secret** here at the end.
    * **4.** **Save credentials** comes last.
  </Step>

  <Step title="Enable the Google APIs">
    The link from OneCLI enables all the Google APIs at once. To open it directly: [enable the Google APIs](https://console.cloud.google.com/flows/enableapi?apiid=gmail.googleapis.com,admin.googleapis.com,analyticsdata.googleapis.com,calendar-json.googleapis.com,chat.googleapis.com,classroom.googleapis.com,people.googleapis.com,docs.googleapis.com,drive.googleapis.com,forms.googleapis.com,meet.googleapis.com,photoslibrary.googleapis.com,searchconsole.googleapis.com,sheets.googleapis.com,slides.googleapis.com,tasks.googleapis.com,youtube.googleapis.com).

    <Frame caption="Confirm the project, then enable the APIs.">
      <img src="https://mintcdn.com/chartdbinc/uEKrweRjk4fPb19Z/images/integrations/google/02-enable-apis.png?fit=max&auto=format&n=uEKrweRjk4fPb19Z&q=85&s=47fcb30dd5c789d9c9f2046adf17b3fe" alt="Google Cloud Enable access to APIs page with the project picker and the Next button." width="1973" height="517" data-path="images/integrations/google/02-enable-apis.png" />
    </Frame>

    * **1.** Check the project. Pick or create the project for OneCLI here.
    * **2.** Click **Next**, then **Enable**.

    <Warning>
      Don't skip this step. If an API isn't enabled, the app connects but every agent request fails with `SERVICE_DISABLED`.
    </Warning>
  </Step>

  <Step title="Choose who can sign in">
    Go to [Google Auth Platform → Audience](https://console.cloud.google.com/auth/audience). If Google asks you to set up Google Auth Platform first, click **Get started**, enter an app name such as `OneCLI` and your support email, then come back here.

    <Frame caption="Pick Internal or External.">
      <img src="https://mintcdn.com/chartdbinc/uEKrweRjk4fPb19Z/images/integrations/google/03-audience.png?fit=max&auto=format&n=uEKrweRjk4fPb19Z&q=85&s=038fc699e380ce25be79316d042de5a4" alt="Google Auth Platform Audience page showing User type Internal and the Make external button." width="1291" height="504" data-path="images/integrations/google/03-audience.png" />
    </Frame>

    * **1.** Open **Audience**.
    * **2.** Choose the user type:

    | User type | Who can connect | Choose it when |
    | - | - | - |
    | **Internal** (recommended) | Only accounts in the Google Workspace that owns this project | Everyone connecting uses your company Google accounts |
    | **External** | Accounts you add as **Test users** while in Testing | People sign in from another Workspace or personal Gmail |

    For **External**, click **Make external**, keep **Testing**, and add every person who will connect under **Test users** (up to 100).
  </Step>

  <Step title="Create the client">
    Go to [Google Auth Platform → Clients](https://console.cloud.google.com/auth/clients).

    <Frame caption="Start a new OAuth client.">
      <img src="https://mintcdn.com/chartdbinc/uEKrweRjk4fPb19Z/images/integrations/google/04-clients.png?fit=max&auto=format&n=uEKrweRjk4fPb19Z&q=85&s=08d2eee5abe08387b6b81329aeed68f9" alt="Google Auth Platform Clients page with the Create client button." width="1831" height="457" data-path="images/integrations/google/04-clients.png" />
    </Frame>

    * **1.** Open **Clients**.
    * **2.** Click **Create client**.

    <Frame caption="Web application, named OneCLI.">
      <img src="https://mintcdn.com/chartdbinc/uEKrweRjk4fPb19Z/images/integrations/google/05-create-client.png?fit=max&auto=format&n=uEKrweRjk4fPb19Z&q=85&s=dcfdce07dd08bedee1ddcb406c2acc1d" alt="Create OAuth client ID form with Application type Web application and Name OneCLI." width="1104" height="587" data-path="images/integrations/google/05-create-client.png" />
    </Frame>

    * **1.** Set **Application type** to **Web application**.
    * **2.** Set **Name** to `OneCLI`.

    <Frame caption="Add the Redirect URI from OneCLI.">
      <img src="https://mintcdn.com/chartdbinc/uEKrweRjk4fPb19Z/images/integrations/google/06-redirect-uri.png?fit=max&auto=format&n=uEKrweRjk4fPb19Z&q=85&s=f8fa71a454b7945a770a7824d80ef601" alt="Authorized redirect URIs section with the OneCLI redirect URI filled in." width="1104" height="599" data-path="images/integrations/google/06-redirect-uri.png" />
    </Frame>

    * **1.** Under **Authorized redirect URIs**, click **Add URI**.
    * **2.** Paste the **Redirect URI** you copied from OneCLI. It ends in `/v1/apps/oauth/google/callback`. One URI covers every Google app. Google only accepts `https` URIs, except for `localhost`.

    Leave **Authorized JavaScript origins** empty. Click **Create**, then copy the **Client ID** and **Client secret** from the dialog.
  </Step>

  <Step title="Save in OneCLI and connect">
    1. Back in OneCLI, paste the **Client ID** and **Client Secret**, then click **Save credentials**.
    2. Open any Google app, for example **Google Drive**, and click **Connect**. You don't need to enter credentials again for other Google apps.
    3. Sign in with Google and click **Allow**. With **External** in Testing, Google first shows **Google hasn't verified this app**. Click **Continue**.
    4. Ask your agent for something simple, such as "List my 5 most recent Drive files."

    <Check>
      **Setup complete.** Every Google app now uses your client, in every workspace you saved it for.
    </Check>
  </Step>
</Steps>

## Where credentials apply

| Saved in | Applies to |
| - | - |
| **Global Connections** (organization) | Every Google app in every workspace |
| A workspace's **Connections** | Every Google app in that workspace only. Overrides the organization's client. |

Removing a workspace's credentials returns it to the organization's client. Saving or removing credentials disconnects the Google accounts that used the previous client, so people need to reconnect. Your first organization save also disconnects accounts connected through OneCLI's built-in Google client.

## Troubleshooting

<AccordionGroup>
  <Accordion title="Error 403: org_internal">
    The app is **Internal** and the account signing in isn't in the Google Workspace that owns the project. Either sign in with an account from that Workspace, or switch the app to **External** and add the account as a test user (step 3).
  </Accordion>

  <Accordion title="Error 400: redirect_uri_mismatch">
    The Redirect URI in Google doesn't exactly match OneCLI's. Copy it again from the OneCLI form and paste it into the client's **Authorized redirect URIs**. Check `https`, the host, and that it ends in `/v1/apps/oauth/google/callback`. Changes can take a few minutes.
  </Accordion>

  <Accordion title="SERVICE_DISABLED or API has not been used in project">
    The Google API for that app isn't enabled in this project. Repeat step 2 in the same project as the client, wait a minute, and retry. You don't need to reconnect.
  </Accordion>

  <Accordion title="Error 403: access_denied">
    The app is **External** in Testing and this account isn't a test user. Add it under **Audience → Test users**.
  </Accordion>

  <Accordion title="Error 400: admin_policy_enforced or Access blocked">
    Your Google Workspace admin restricts third-party apps. In the [Google Admin console](https://admin.google.com/), go to **Security → Access and data control → API controls → Manage third-party app access**, and mark the OneCLI client as **Trusted** using its Client ID.
  </Accordion>

  <Accordion title="Error 401: invalid_client">
    The Client ID or secret is wrong, or the client was deleted. Copy both again from **Clients** and save them in OneCLI.
  </Accordion>

  <Accordion title="Connections stop working after 7 days">
    Google expires refresh tokens after 7 days for **External** apps in **Testing**. Use **Internal**, or publish the app under **Audience → Publish app**. Publishing an app that uses Gmail or Drive scopes may require Google verification.
  </Accordion>
</AccordionGroup>

## Next steps

* [Grant the connection to an agent](/docs/guides/agent-access).
* [Add organization-wide rules](/docs/guides/rules).
* See what each app can do: [Gmail](/docs/integrations/gmail), [Google Calendar](/docs/integrations/google-calendar), [Google Drive](/docs/integrations/google-drive), and the other Google pages.


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