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

# Google

> Connect GAIA to Gmail, Calendar, Drive, and other Google Workspace APIs.

<Info>
  **Connector ID:** `google` · **Type:** `oauth_pkce` · **Catalog entry:** [`src/gaia/connectors/catalog/google.py`](https://github.com/amd/gaia/blob/main/src/gaia/connectors/catalog/google.py)
</Info>

## What you'll need

Google requires every desktop app — including GAIA running locally — to
identify itself with an **OAuth client** that you create in your own
Google Cloud project. This sounds heavy, but for a single-developer
machine it takes about three minutes and is free.

You will create one OAuth client and paste two values into the GAIA
Agent UI: a **Client ID** and a **Client Secret**. After that, GAIA
stores them encrypted in your OS keyring and you never need to think
about them again.

## Step 1 — Create a Google Cloud project

If you already have a project you use for hobby projects, skip ahead.
Otherwise:

1. Go to the [Google Cloud Console](https://console.cloud.google.com/).
2. Click the project dropdown at the top → **New project**.
3. Name it something like `gaia-personal` and click **Create**.

## Step 2 — Enable the APIs you want to use

GAIA only sees the Google APIs you explicitly enable on the project.
For a typical setup enable at least:

* **Gmail API** — to read/send mail
* **Google Calendar API** — to read/create events
* **Google Drive API** — to read/manage files

In the Cloud Console, go to **APIs & Services → Library**, search for
each API by name, click it, and click **Enable**.

## Step 3 — Configure the OAuth consent screen

Google requires you to fill in a consent-screen form before it will
issue OAuth credentials, even for personal-use apps.

1. Go to **APIs & Services → OAuth consent screen**.
2. Pick **External** as the user type and click **Create**.
3. Fill in the required fields:
   * **App name**: `GAIA Personal` (or whatever)
   * **User support email**: your email
   * **Developer contact email**: your email
4. Click **Save and Continue** through the Scopes and Test users
   pages — leave them empty for now. You'll add yourself as a test
   user in the next step.

### Add yourself as a test user

While the app is in **Testing** publishing status (the default), only
test users can authenticate. Add your own Google account:

1. **OAuth consent screen → Test users → Add users**.
2. Enter your Google email and **Save**.

You can stay in Testing mode indefinitely if you only use this for
yourself — there's no need to verify the app for personal use.

## Step 4 — Create the OAuth client

This is the credential GAIA uses.

1. Go to **APIs & Services → Credentials → Create credentials → OAuth
   client ID**.
2. **Application type**: **Desktop app**. <Tooltip tip="GAIA is a
   desktop application that runs a temporary loopback web server on
   127.0.0.1 to receive the OAuth callback. The 'Desktop app' type is
   the right one — 'Web application' would require a fixed redirect URL
   that GAIA can't provide.">Why Desktop app?</Tooltip>
3. **Name**: `GAIA` (or whatever you want).
4. Click **Create**. A dialog shows the **Client ID** and **Client
   Secret**. **Copy both** — you'll paste them into GAIA in a moment.
   You can also download the JSON.

<Warning>
  Even though "Desktop app" clients are technically public (the secret
  isn't a real secret in the cryptographic sense), Google's token
  endpoint requires `client_secret` to be present in every exchange.
  Don't omit it.
</Warning>

## Step 5 — Paste credentials into GAIA

1. Launch the Agent UI: `gaia chat --ui`.
2. Click **Settings** (gear) → **Connections**.
3. Click the **Google** tile to expand it.
4. Paste the **Client ID** and **Client Secret** from Step 4.
5. Click **Save & Connect**.

GAIA will:

1. Store the credentials in your OS keyring (macOS Keychain on Mac,
   gnome-keyring/kwallet on Linux, Credential Locker on Windows).
2. Open Google's consent screen in your default browser.
3. Receive the callback on a temporary loopback server.
4. Exchange the auth code for a refresh token (also stored in the
   keyring).

The tile flips to **Connected as [your.email@gmail.com](mailto:your.email@gmail.com)** once the flow
completes.

## Step 6 — Grant scopes to specific agents

Connecting Google doesn't automatically give every agent access to
your inbox. Each agent must be granted the specific scopes it needs.
You can do this in the UI or the CLI:

```bash theme={null}
# Grant the chat agent read-only Gmail access
gaia connectors grants grant google builtin:chat \
  --scopes https://www.googleapis.com/auth/gmail.readonly
```

The default scopes a connection is established with are listed in the
spec at
[`src/gaia/connectors/catalog/google.py`](https://github.com/amd/gaia/blob/main/src/gaia/connectors/catalog/google.py).

## Common issues

### `redirect_uri_mismatch`

You probably picked **Web application** instead of **Desktop app** in
Step 4. Delete the OAuth client and create a new one with the right
type — Web application clients require a registered redirect URI,
which GAIA can't provide because it picks an ephemeral port.

### `Access blocked: ... has not completed Google verification`

Add yourself as a test user (Step 3, "Add yourself as a test user").
Apps in Testing mode only allow listed test users.

### `Error 400: invalid_grant` after a long while

Refresh tokens expire if your app stays in Testing mode for more than
seven days without use. Reconnect from the Agent UI's Connections
panel — it will issue a new refresh token.

### `client_secret is missing`

You either skipped pasting the Client Secret in Step 5, or the
connection blob in your keyring predates a GAIA upgrade. Disconnect
and reconnect from the UI to reset.

## Revoking access

Two places — both work:

* **From GAIA**: Settings → Connections → Google → **Disconnect**.
  Removes the refresh token from the keyring; the next API call
  errors with `NOT_CONNECTED`.
* **From Google**: <a href="https://myaccount.google.com/permissions" target="_blank">myaccount.google.com/permissions</a> → find your
  OAuth client → **Remove access**. Useful if you've lost the laptop
  the keyring lives on.

## See also

* [Connectors overview](/docs/connectors)
* [Google Cloud Console — OAuth 2.0 credentials](https://cloud.google.com/docs/authentication/provide-credentials-adc)
* [Google APIs Explorer](https://developers.google.com/apis-explorer)
* [Connectors security model](/docs/security/connections)