Skip to main content

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.

Connector ID: google · Type: oauth_pkce · Catalog entry: src/gaia/connectors/catalog/google.py

​
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.
  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. 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.
  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.
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.

​
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 [email protected] 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: 
# 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.

​
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: myaccount.google.com/permissions → find your OAuth client → Remove access. Useful if you’ve lost the laptop the keyring lives on.

​
See also