Google Drive connector setup

Operator·6 minutes to read

This page is the setup half — creating the OAuth app Google Drive needs in Google's own console and getting its client id and secret into this deployment. Authorising a connection afterwards is the Authenticate control on the plugin sheet, which is what actually sends you to Google.

1. Create the OAuth app in the Google Cloud console

  1. Open the Google Cloud console and create a project (or pick an existing one) — this is your own project, not Botseon's. Enable the Google Drive API (APIs & Services → Library), fill in the OAuth consent screen, and create an OAuth client ID of type Web application under APIs & Services → Credentials.

  2. Under Authorized redirect URIs, add the redirect URL from docs/connectors/README.md — with the quickstart's default BOTSEON_PUBLIC_URL, that is:

    http://127.0.0.1:3000/api/oauth/google-drive/callback

  3. Create it. Google shows you a client ID and a client secret once — copy both now.

2. Scopes

Request the narrowest pair that covers the tools this connector exposes (F-PLUG-1: minimum scopes per capability, read and write requested separately):

  • https://www.googleapis.com/auth/drive.readonly — read files and their metadata; no writes.
  • https://www.googleapis.com/auth/drive.file — create and edit only the files this connector itself created or opened; no access to the rest of the drive.

3. Enter the app

One command, with the client secret on standard input — there is no flag that takes it and no environment variable that holds it (see docs/connectors/README.md):

printf %s "$CLIENT_SECRET" | botseon oauth-app set \
  --org <organisation id> --slug google-drive \
  --client-id <the client ID from step 1> \
  --auth-url https://accounts.google.com/o/oauth2/v2/auth \
  --token-url https://oauth2.googleapis.com/token \
  --revoke-url https://oauth2.googleapis.com/revoke \
  --configured-by <your user id>

It stores the secret encrypted and prints the redirect URL from step 1 back, so you can check the two match. botseon oauth-app show --org <organisation id> --slug google-drive says whether an app is configured and under which client id; nothing prints the secret back.

Never put either value in a bot's description, a memory, or anywhere else a model reads as ordinary text.

4. Sharing a file with people

google-drive.share_file gives one to ten people access to one Drive file. Each person gets their own permission, as a viewer, a commenter or an editor, and Drive emails each of them that the file was shared. A file in a shared drive works the same way.

  • The approval step. Sharing sends a file out of the member's account, so every share waits for the member's approval. The card names the file by its Drive name, lists every person, and says the access in plain words: "can view", "can comment" or "can edit". Nothing reaches Google until the member approves, and Deny sends nothing. The bot must give the file's name with every share, so the card never shows a bare id. Before sharing, the bot checks that name with Drive, so the card cannot name one file while the call shares another.
  • Some people refused. If Google refuses some of the addresses, the people it accepted keep their access, and the run ends with a sentence naming who got access and who did not. It is not reported as a success.
  • The drive.file limit. The write scope is drive.file, so the connector can share only files it created or that the member opened with it. For any other file, Google answers 403 or 404, and the member reads: "I can only share files I created or that you opened with me." The connection stays connected, with no reconnect prompt, because the grant is fine and the file is simply out of its reach. The connector does not ask for the full drive scope: Google treats that as a restricted scope and requires a security review before an app may use it.
  • A read-only connection. With only drive.readonly, the bot is not offered the tool at all, and the driver refuses it locally before any request.

5. Slide decks delivered as Google Slides

A member who asks for a deck in Google Slides gets it through google-drive.upload_file with convertTo: "google-slides": the bot builds the .pptx on its computer, uploads it into the folder the member chose, and Drive imports it as a native Google Slides presentation. There is nothing to set up for it.

  • No new scope. The import is an ordinary upload that names the Google Slides type as its target, so the existing drive.file write grant covers it and the consent screen does not change. The vendor facts are in docs/research/connectors/google-drive-slides-import-2026-10-21.md.
  • The approval step. It is the same upload card as any other file: nothing reaches Google until the member approves.
  • Limits. Only a .pptx converts; any other type with convertTo is refused before a request. The 5 MB cap of a single upload holds for a deck too. Above it the bot shares the .pptx in the conversation instead.
  • Checking it. A converted presentation has no md5Checksum in Drive, so the tool answers storedMd5: null for it. A missing checksum on a converted file is expected and is not a failed upload.

6. Editing Google Docs and Google Slides in place

google-drive.edit_doc and google-drive.edit_slides change a Doc or a presentation in place: replace text, add text at the end of a Doc or after a passage in it, add a slide with a title and a body, or remove a slide. Each call is one read and one batchUpdate on Google's own Docs or Slides API. The vendor facts are in docs/research/connectors/google-docs-slides-edit-2026-10-21.md.

  • Enable two APIs, once. In the Google Cloud console of the project that owns this OAuth app, open APIs & Services → Library and enable the Google Docs API and the Google Slides API. Until you do, every edit ends with "The Google Docs API is not switched on in this deployment’s Google Cloud project" (or the Slides one), and nothing else breaks.
  • No new scope. Both APIs accept drive.file, so the consent screen in step 2 stays as it is and members do not reconnect. The edits reach the same files as every other write here: files the connector created and files the member opened with it. Any other file ends with "I can only edit files I created or that you opened with me." The connector does not ask for the documents or presentations scopes, which would reach every Doc and deck in the account.
  • The approval step. Both tools are writes: the member approves the card first, and Deny sends nothing to Google.
  • Nothing half done. The driver locates every passage and slide number before it writes. A passage that is not in the Doc, or a slide number the deck does not have, sends nothing.
  • Checking it. The nightly connector-live run edits a Doc and a deck it made in the Botseon Test folder and reads the change back (docs/operations/connector-live-setup/google-drive-docs-slides.md).

Last verified against build 445930e.