Guides · Setup

Connect Google Docs to Outloop

Last updated: August 17, 2026

What this setup gives you

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

• →An agent can create a document, then insert and format text, tables and structural elements in an approved document.
• →Each client workspace is pinned to its own documents — 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 documents — you will sign in as it in your browser.
• ✓The document IDs the workspace should be allowed to touch (the segment between /d/ and /edit in the document URL).
• ✓Outloop installed and activated, with a workspace selected.

Which Google account connects what

1. Enable the Google Docs API

In Google Cloud Console, open APIs & Services → Library, search Google Docs API, and click Enable. Outloop calls it at docs.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/documents
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 Docs in Outloop

In Outloop, open API Keys & Access → Add an API key and choose Google Docs. 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 documents — read, create, insert and format content (recommended)
• →Read-only documents

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 Docs in your browser. Google's own sign-in opens and shows an account chooser — pick the account that can open the client documents, 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 documents
• ✓Create new documents
• ✓Insert and format text, tables and lists

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

• ⚠Delete document content

Then click Confirm — this is the approved account.

6. Save the Access Profile and approve the documents

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 document IDs this workspace may touch into Approved documents, one per line — the ID is the segment between /d/ and /edit in the document URL.

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

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 document:

{
  "tenant": "<WORKSPACE_ID>",
  "service": "google_docs",
  "verb": "api_bridge.request",
  "method": "GET",
  "path": "/v1/documents/<DOCUMENT_ID>?fields=documentId"
}

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

decision: allow
HTTP 200
documentId matches the approved document
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 document and no explicit account-wide setting — every agent call is refused with CUSTOMER_RESOURCE_PIN_REQUIRED.
• →A document 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 document 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 Docs can open

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

• →Test with a document that the exact account shown under Connected as on the Docs 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 Sheets and Google Slides guides, which share this behaviour.

What bites people about the Docs API

A Google Doc is not a text blob you overwrite — it is an ordered structure addressed by numeric position, and that single fact causes most first-attempt failures. Worth putting in the agent's instructions up front.

Every insertion moves everything after it

Positions are indexes measured in UTF-16 code units, and Google's own documentation is blunt about the consequence: each insertion "increments all the higher-numbered indexes by the size of the inserted text," and deleting text "alters the indexes of all the text that follows in the segment." An agent that plans five edits against one read of the document, then applies them top to bottom, gets the first one right and the other four progressively more wrong.

Indexes are per segment, not per document

The body, each header, each footer and each footnote are separate segments with their own index space. An index that means one thing in the body means something else in a header, so a request has to name the segment it belongs to. This is a common source of an edit landing in a plausible but wrong place.

Formatting is a separate request from the text

Inserting text and styling it are two different operations over the same range, which means the range has to still be correct when the styling request runs — the same index-shifting problem, one step later. Batch the insert and its styling together and order the whole batch back to front.

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 document, inserted and formatted text, tables and structural elements, 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 document 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 documents — 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 documents; 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 Docs 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 document and has not been set to account-wide. Add at least one document ID under Approved documents, or choose account-wide deliberately — then save the Access Profile.

A specific file returns RESOURCE_ID_NOT_ALLOWED

That document 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 document 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 document ID afterwards; Outloop never widens a pin on its own.

Rotate or revoke access

• →Narrow a workspace — remove document IDs from Approved documents 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 Docs 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 Docs API reference — documents.get, documents.create and batchUpdate request shapes.
• →Docs API how-tos — structural elements, text insertion and formatting.
• →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.