Guides · Setup

Connect Google Sheets to Outloop

Last updated: August 17, 2026

What this setup gives you

Agents that can do real Sheets work inside the client files you approved — and nothing outside them. Outloop holds the Google credential locally, decides which spreadsheet each workspace may reach, and audits every request.

• →An agent can create a spreadsheet, then write values, formulas and formatting into an approved spreadsheet.
• →Each client workspace is pinned to its own spreadsheets — one agency Google account, many separated clients.
• →The refresh token is minted host-side and never appears on your clipboard, in a screenshot, or in a prompt.
• →A wrong-file request is refused before any call reaches Google, not after.

What you need before starting

• ✓Access to a Google Cloud project with the OAuth consent screen configured.
• ✓A Client ID and Client Secret for your first Google connector. After that, Outloop reuses the saved Google OAuth app and never asks for the secret again.
• ✓The Google account that can open the client spreadsheets — you will sign in as it in your browser.
• ✓The spreadsheet IDs the workspace should be allowed to touch (the segment between /d/ and /edit in the spreadsheet URL).
• ✓Outloop installed and activated, with a workspace selected.

Which Google account connects what

1. Enable the Google Sheets API

In Google Cloud Console, open APIs & Services → Library, search Google Sheets API, and click Enable. Outloop calls it at sheets.googleapis.com.

2. Create the OAuth client (once, for all Google connectors)

In Google Auth Platform → Clients, create a Web application OAuth client and copy the Client ID and Client Secret. Google may show the secret only once; if you lose it, create a new one. Under Authorized redirect URIs add Outloop's local callback — without it the browser connect below fails with redirect_uri_mismatch:

http://127.0.0.1:44317/oauth2/callback

The full one-time Google Cloud walkthrough — project, APIs, the whole scope set in one paste, and the publishing-status step that stops a working connection expiring after about a week — is in Set up one reusable Google Cloud OAuth app. If you already have a saved Google OAuth app, there is nothing to create here. The scope this connector requests is:

https://www.googleapis.com/auth/spreadsheets
openid
email

The openid and email scopes are how Outloop verifies which Google account you actually connected — that identity check is Google OIDC, and it does not involve any Drive scope.

Shared agency app or workspace-dedicated?

3. Add Google Sheets in Outloop

In Outloop, open API Keys & Access → Add an API key and choose Google Sheets. The panel opens on Connect in your browser, with the Cloud Console detail in the collapsed Setup details — Google Cloud OAuth client, scopes and caveats and Before you connect disclosures.

Under Access to request from Google, choose the level:

• →Full spreadsheets — read, create, edit values, formulas and formatting (recommended)
• →Read-only spreadsheets

The full option is preselected because it is what most agency work needs; read-only is offered but never preselected. Then check the Google OAuth app dropdown — a saved profile supplies the app with no Client Secret to re-enter.

4. Connect the account in your browser

Click Connect Google Sheets in your browser. Google's own sign-in opens and shows an account chooser — pick the account that can open the client spreadsheets, then approve the consent screen. Google hands back to Outloop on a local loopback callback and Outloop mints and stores the refresh token host-side.

5. Confirm the account and capabilities

Outloop shows Connected as the Google account you just used. Check it — this is the moment to catch a sign-in to the wrong account, before any agent touches client work.

Under Agents will be able to (change any time in the Access profile), these are on by default:

• ✓Read spreadsheets
• ✓Create new spreadsheets
• ✓Edit cells, formulas and formatting

And these are unchecked, marked ⚠, and only run if you turn them on:

• ⚠Erase the contents of cells
• ⚠Delete tabs, rows and columns

Then click Confirm — this is the approved account.

6. Save the Access Profile and approve the spreadsheets

This is the step that separates clients, and the one people skip. Connecting the account is not the same as granting access to a file. On the connector's card, paste the spreadsheet IDs this workspace may touch into Approved spreadsheets, one per line — the ID is the segment between /d/ and /edit in the spreadsheet URL.

Approved spreadsheets:
1AbCdEf...              # client A — spreadsheet the agent may edit
2GhIjKl...              # client B — a second approved spreadsheet

Or, in the Access section, choose Account-wide deliberately. There are only two modes, and the safe pinned one is the default. Then click Save Access Profile — until you do, Copy workspace run prompt stays disabled.

7. Run the first proof

Ask the agent for a safe read against an approved spreadsheet:

{
  "tenant": "<WORKSPACE_ID>",
  "service": "google_sheets",
  "verb": "api_bridge.request",
  "method": "GET",
  "path": "/v4/spreadsheets/<SPREADSHEET_ID>?fields=spreadsheetId"
}

Use a real spreadsheet ID that the connected account can open — never a guessed one. Success criteria:

decision: allow
HTTP 200
spreadsheetId matches the approved spreadsheet
secret_exposed: false
audit entry exists

Only the last line completes the proof. A grant preflight that passes, or an OAuth callback that succeeded, is not runtime verification — the provider request has to succeed against a real resource first.

What happens when nothing is approved

Outloop fails closed here, which is the behaviour you want and the most common first confusion:

• →No approved spreadsheet and no explicit account-wide setting — every agent call is refused with CUSTOMER_RESOURCE_PIN_REQUIRED.
• →A spreadsheet that is not on the list — refused with RESOURCE_ID_NOT_ALLOWED.
• →Both refusals happen before the credential is read — no Google call is made, and nothing is charged against your quota.
• →Creating a new spreadsheet while pinned is refused too. Approve the new ID afterwards; Outloop never widens a pin by itself.

A file Drive can see is not a file Sheets can open

Google Drive and Google Sheets are separate connectors in Outloop, and they can be authenticated as different Google accounts. Finding a spreadsheet through the Drive connector therefore proves nothing about whether the Sheets connector's identity can open it.

• →Test with a spreadsheet that the exact account shown under Connected as on the Sheets connector owns or has been explicitly shared.
• →An HTTP 403 on one document is normally a file-permission result for that identity. On its own it does not prove a missing scope, a disabled API, or a broken connector.
• →"API Enabled" in Google Cloud does not prove a specific account can open a specific file. It only means the API exists for the project.
• →Prove access on a file you know that identity owns before you start changing scopes — changing scopes to fix a permission problem widens access without fixing anything.

See the Google Drive setup guide for the Drive-side boundary, and the Google Docs and Google Slides guides, which share this behaviour.

What bites people about the Sheets API

Access is only half the job. These are the Sheets-specific behaviours that make an agent's write land wrong even when the connector is working perfectly — worth putting in the agent's instructions up front.

RAW vs USER_ENTERED decides whether a formula is a formula

Every write carries a valueInputOption. With RAW, Google's docs are explicit that the input is not parsed — =1+2 lands as the literal text =1+2. With USER_ENTERED, the value is parsed exactly as if typed into the UI, so =1+2 becomes a formula and Mar 1 2016 becomes a date. An agent writing formulas or dates with RAW produces a sheet full of inert strings that looks fine until someone tries to sum it.

update, append and batchUpdate are three different operations

• →update writes one range, and takes valueInputOption as a query parameter.
• →batchUpdate writes several discontinuous ranges in one call, and takes valueInputOption in the body instead.
• →append looks for the last table within the range you name and adds rows after it, starting at the first column — so the row it writes to is Google's decision, not yours.

A1 notation without a sheet name means the first sheet

A range like A1:B2 with no sheet prefix targets the first sheet in the spreadsheet — not the one that happens to be open, and not the one the agent was told about. Have agents always qualify the tab ('Client Report'!A1:B2). And when a range names multiple cells, the data has to fit inside it; a single cell like A1 lets the write extend outward as needed.

Changing the account or the credential later

Verified vs not claimed yet

"Verified" here means a real proof passed through Outloop in a workspace — it is never a product-level claim about the connector.

• Verified A full real workflow through Outloop — created a spreadsheet, wrote values, formulas and formatting, and read them back — using files created for the proof.
• Verified An audited read through a pin created in the dashboard: decision: allow, HTTP 200, secret_exposed: false.
• Verified Wrong-resource denial (RESOURCE_ID_NOT_ALLOWED) and no-pin denial (CUSTOMER_RESOURCE_PIN_REQUIRED), both at zero Keychain reads.
• Verified Several Google connectors sharing one OAuth app, each holding its own distinct refresh token.
• Verified The audit contained no spreadsheet content and no secrets.
• Not claimed Anything on a machine other than the Mac this was proven on. Outloop is at controlled design-partner stage — reproduce it on your own Mac before relying on it for client work.
• Not claimed That a successful OAuth callback means the connector is ready. It means Google accepted the sign-in — nothing more until a provider request succeeds.

Troubleshooting

Google shows an account chooser

Expected. Outloop asks Google for the chooser on purpose, so a sign-in can never silently reuse whichever account your browser happened to be logged into. Pick the account that owns or can open the client's spreadsheets — which is often not the account that manages the Google Cloud project.

“Google hasn’t verified this app”

This appears because the OAuth app is your own and has not been through Google's verification. If it is your app and you trust it, expand Advanced and continue. If you do not know who owns the app, stop — that warning is doing its job, and clicking past an unknown app is not a routine step.

Which audience the app uses decides who can get that far at all. An External app in Testing only admits accounts added as Test users. An Internal app only admits accounts inside its Google Workspace organisation. For customer-facing production use, complete Google's verification rather than living in Testing.

The wrong Google account got connected

Use Connect as a different Google account on the connector. It keeps the same Client ID and Client Secret and reopens Google's chooser. The stored token is only replaced once Outloop verifies the new identity is the intended one — if it does not match, Outloop reports the mismatch and keeps the previous credential. Nothing is lost by trying.

A credential that works but sits on the wrong account is deliberately not marked runtime-verified for that workspace. Working and correct are different things.

BACKEND_AUTH_FAILED during connect

Google rejected the sign-in, so the new credential failed Outloop's safe verification. The important part: the previous credential is unchanged. Do not delete the connector, the OAuth app or the workspace as a first move. Check, in this order — that you signed in as the account that can reach the client's spreadsheets; that the account is admitted by the app's audience (a Test user on an External+Testing app); and that the API is enabled in the right Cloud project. Then try the connect again.

Reconnecting never asked for the Client ID and Secret

Expected. Disconnecting a Google Sheets credential does not delete your saved Google OAuth app profile — that is a separate object, kept on purpose so later connectors do not re-enter a Client Secret. Outloop reused it. If you specifically want a different app, pick another saved profile from the Google OAuth app dropdown, or create a new one and save it alongside. This is reuse working, not a stale credential silently retained.

“Copy workspace run prompt” is not available

The Access Profile has not been saved yet. Open the Access Profile, choose the reach and the capabilities, and click Save Access Profile — the run prompt becomes available once the authorization is recorded. OAuth succeeding is not the same as the workspace being authorized, and this is the step that closes the gap.

The connection stops working after about a week

If the OAuth app's audience is External and its publishing status is still Testing, Google expires refresh tokens for that app after roughly seven days. Two honest options: publish the app to In production, or use an Internal audience if everyone signing in is inside your Google Workspace organisation. Publishing may require Google's verification review depending on the scopes the app requests — that is Google's process and its outcome and timing are not ours to promise.

Every call returns CUSTOMER_RESOURCE_PIN_REQUIRED

The workspace has no approved spreadsheet and has not been set to account-wide. Add at least one spreadsheet ID under Approved spreadsheets, or choose account-wide deliberately — then save the Access Profile.

A specific file returns RESOURCE_ID_NOT_ALLOWED

That spreadsheet is not on the approved list for this workspace. Add its ID — and check you are adding it to the right workspace, because this refusal is usually correct.

A specific file returns HTTP 403 from Google

This is a Google answer, not an Outloop refusal — the request reached Google and that account was not allowed to open that file. Check the account under Connected as and share the spreadsheet with it, or connect as an account that already has access. Do not widen the OAuth scope to fix a sharing problem.

The agent created a file and then could not use it

Expected while pinned. Approve the new spreadsheet ID afterwards; Outloop never widens a pin on its own.

Rotate or revoke access

• →Narrow a workspace — remove spreadsheet IDs from Approved spreadsheets and save. Reach shrinks immediately; the credential is untouched.
• →Rotate the token — use Re-authenticate on the connector. Same account, fresh authorization.
• →Revoke everything for this connector — remove the Google Sheets credential in Outloop, then revoke Outloop's access for that account at myaccount.google.com/permissions. Do both: removing the local credential does not revoke the grant at Google.
• →Retire the OAuth app — delete the client in Google Auth Platform → Clients. This breaks every Google connector still using that saved app profile, so move them first.

Official Google documentation

• →Google Sheets API reference — endpoints, request shapes and field masks.
• →Sheets API OAuth scopes — what each scope permits.
• →OAuth app audience and publishing status — Internal vs External, Testing, and Test users.
• →Using OAuth 2.0 to access Google APIs — refresh-token behaviour, including the Testing-status expiry.

Outloop is an independent tool and is not affiliated with or endorsed by Google. See the security model, the Google Drive setup guide, or the full guide index.