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

# Let AI Agents Read and Update Google Sheets

> Connect Google Sheets so agents can read ranges, append rows, and build reports. OAuth tokens are injected by the gateway and never reach the agent.

> [!WARNING]
>
> **Per-app Google setup is deprecated.** All Google apps now share one Google OAuth client and one Redirect URI. To use your own client, follow the [Google setup guide](/docs/integrations/google.md). Credentials saved for one Google app apply to all of them.

## Overview

Buckle connects AI agents to Google Sheets through Google's OAuth flow. Agents can read spreadsheet data, write values, create new sheets, and manage formatting. The gateway injects OAuth credentials into requests to the Google Sheets API automatically.

This is useful for agents that need to extract data from spreadsheets, generate reports, populate templates, or sync data between systems.

## What you will set up

* A Google Sheets connection through Google OAuth, in one click on Buckle Cloud or with your own Google client
* Automatic token injection on requests to the Google Sheets API
* Per-agent, per-tool access, such as read-only for reporting agents

## Connect on Buckle Cloud (one click)

**1. Open the app**

Open the Buckle dashboard and navigate to **Settings** > **Apps** > **Google Sheets**.

**2. Authorize**

Click **Connect Google Sheets**. You'll go straight to Google: pick your account, review the permissions, and click **Allow**. No Google Cloud setup needed.

On self-hosted Buckle, or to use your own Google client on Cloud, see [Use your own Google client](#self-hosted).

## Use your own Google client

> [!NOTE]
>
> This is for self-hosted Buckle, and for Buckle Cloud when you choose **Custom credentials** instead of one-click. One Google client serves every Google app in Buckle, so you set it up once. If you already did it for another Google app, skip to step 2.

> [accordion] 1. Set up your Google client
>
> Follow the [Google setup guide](/docs/integrations/google.md). It enables the Google APIs, sets up the consent screen, creates the OAuth client, and adds the Redirect URI.
>
> You paste the client into **Settings** > **Apps** > **Google Sheets** > **Custom credentials**, under the Redirect URI the guide asks you to register:
>
> ![Buckle Custom credentials card for Google Sheets with the setup guide link, the Redirect URI and its copy button, and the Client ID and Client Secret fields.](https://mintcdn.com/onecli-17d3f772/hJP3XqgFsBDnXHKy/images/integrations/google-sheets/buckle-custom-credentials-google-sheets.png?fit=max\&auto=format\&n=hJP3XqgFsBDnXHKy\&q=85\&s=19f08a320e644085a2f1ad926aa30ef3)
>
> Custom credentials for Google Sheets in Buckle.

> [accordion] 2. Connect Google Sheets
>
> Open **Settings** > **Apps** > **Google Sheets**, select **Connect Google Sheets**, pick your Google account, and click **Allow**.
>
> ![Buckle connect window for Google Sheets showing Configuration required and the Configure credentials button.](https://mintcdn.com/onecli-17d3f772/hJP3XqgFsBDnXHKy/images/integrations/google-sheets/buckle-connect-google-sheets.png?fit=max\&auto=format\&n=hJP3XqgFsBDnXHKy\&q=85\&s=425a629c1217f1d35eacce23f7b0205d)
>
> The Google Sheets connect window before a Google client is set up.

## What agents can do

* Read cell values from specific ranges (e.g., `Sheet1!A1:D10`)
* Write values to individual cells or ranges
* Append rows to the bottom of a sheet
* Create new spreadsheets with specified titles and initial data
* Add, rename, and delete sheets within a spreadsheet
* Read and apply cell formatting (bold, colors, borders, number formats)
* Create and manage named ranges
* Read spreadsheet metadata (title, sheets, locale)
* Clear cell contents in a specified range
* Batch read or write multiple ranges in a single request

## Controlling access

Access is per agent: [grant](/docs/guides/agent-access.md) the connection to each agent that needs it, choosing per tool what runs freely, what needs human approval, and what stays blocked — a read-only agent is a single grant. Organization [rules](/docs/guides/rules.md) add guardrails on top, like rate limits and blanket blocks. Everything is checked before credential injection, so a blocked request never reaches Google Sheets.

## FAQ

> [accordion] Can I give an agent read-only access to Google Sheets?
>
> Yes. When you [grant](/docs/guides/agent-access.md) the connection, allow the read tools and block or require approval for writes. A read-only agent is a single grant.

> [accordion] Does the agent see my Google OAuth token?
>
> No. The token stays in Buckle, and the gateway adds it to Sheets API requests at the proxy. The agent makes plain HTTP calls and never holds the credential. See [How it works](/docs/how-it-works.md).

> [accordion] How do I switch Google accounts or reconnect Sheets?
>
> Open **Settings** > **Apps** > **Google Sheets** in the dashboard and connect again with the account you want. Agents with access use the new connection automatically.

> [accordion] Do I need a Google Cloud project?
>
> Not on Buckle Cloud, where one-click connect works out of the box. Self-hosted, or to use your own client on Cloud, follow the [Google setup guide](/docs/integrations/google.md) once for all Google apps.


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