Google connections

What a Google connection is

Google Sheets and Google Drive are connection kinds of their own, in the Services group of Integrations, and flow steps of their own in the add-step menu — Google Sheets (“Read, add or update spreadsheet rows”) and Google Drive (“List, download or upload files”). A step picks a connection; the connection holds the right to act as the person who connected it.

Nobody types a token. The connection is created by Google’s answer: you name it, press Connect with Google (“Google sends you back here once you allow access.”), choose your Google account, allow access, and land back where you started. The card then shows the account’s address and Connected by … · when. What Google returned — a refresh token — is stored as the secret variable GSHEETS_<NAME>_REFRESH_TOKEN (or GDRIVE_…), and every step turns it into a short-lived access token when it runs.

Connect with a service-account key

A service account is a Google account for software. It needs no consent screen and no Google app, so it works at once on any installation. In Google Cloud, enable the Sheets and Drive APIs, create a service account, create a JSON key for it, then drop that file into the dialog (or paste it). Waiso checks the file and keeps only two secret variables — GSHEETS_<NAME>_CLIENT_EMAIL and GSHEETS_<NAME>_PRIVATE_KEY; the rest of the file is never stored.

The service account reaches only what you share with its e-mail (shown in the dialog with a Copy button), like sharing with a person. The steps then list exactly those files, and accept a pasted Sheets or Drive address. A service account has no storage of its own: to create files, choose a folder in a Shared Drive, or replace an existing file.

The Google Sheets and Google Drive steps

Google Sheets works on one tab of one spreadsheet. Pick the spreadsheet — in Google’s own picker (Connect with Google) or from the shared list (service account) — or choose Create a spreadsheet instead. Then Do: Read rows (optionally only where a column equals a value), Add a row, Update a row, Update or add a row, Delete rows or Create a spreadsheet. Columns shows one binding row per header of the tab; bind rows to a list to write many at once. Update, upsert and delete match on the column you choose under Match on; an update that matches nothing changes nothing and says matched: false.

Google Drive lists a folder, downloads a picked file (a file value a File step can read into rows) or uploads a file from an earlier step — as a new file in a folder, or replacing a picked file. Every Run test that writes asks first.

{
  "spreadsheetId": "1AbC…",
  "url": "https://docs.google.com/spreadsheets/d/1AbC…/edit",
  "tab": {
    "id": 0,
    "name": "Sheet1"
  }
}

What Waiso asks Google for

A scope is the permission a consent screen asks for. Waiso asks for the narrowest one each service needs, plus openid email to know which account was connected — and a test in the code fails if anyone adds a broader one:

Because of drive.file, a spreadsheet you never picked is invisible to Waiso, even in your own Drive. That is why the steps choose files through Google’s own picker: picking a file is what grants access to it.

How the sign-in is protected

• The sign-in link is bound to you and expires after 10 minutes; it cannot be replayed.
• Google can only send you back to a page of this installation — never to an address passed in a link.
• Deleting or disconnecting the connection revokes the token at Google too, then removes its variable.

Reconnect and errors

A connection can lose its access: you removed Waiso from your Google account, changed the password, or the installation switched to a different Google app. The card then says Lost access to Google — reconnect it. and Steps using this connection fail until then. Press Reconnect, allow access again, and the same connection — same name, same variable — works again; no flow needs editing.

Set up the Google app

Every Connect with Google goes through one OAuth app registered in Google Cloud. On a self-hosted installation, a super admin creates it once under Settings → Google app (“The Google Cloud app every project uses for Connect with Google.”); How do I set this up? opens the same steps as below, with your exact redirect address filled in.

1. 1
   Create a Google Cloud project

   In the Google Cloud console, create a project for Waiso. No billing account is needed — nothing here is paid.

2. 2
   Turn on the four APIs

   In APIs & Services → Library, enable the Google Sheets API, the Google Drive API, the Gmail API and the Google Picker API.

3. 3
   Set up the consent screen

   Choose External — or Internal if everyone is in your Google Workspace organisation. Add only the scopes drive.file and gmail.send, then publish the app In production: an app left in Testing loses its access after 7 days.

4. 4
   Create the OAuth client

   In Credentials, create an OAuth client ID of type Web application with the Redirect address the panel shows as an authorised redirect URI (it ends in /api/oauth/callback). Paste its Client ID and Client secret.

5. 5
   Add the Picker key and save

   Create an API key restricted to the Google Picker API, copy the Project number from the project’s dashboard, fill Picker API key and Project number, and Save.

The client secret goes in and never comes back: afterwards the field reads Client secret · saved with Replace. Saving a different client warns A different client: the connections made with the old one must reconnect.

Limits

• A connection acts as one Google account — the one that pressed Connect, or the service account. Files that account cannot open, the steps cannot open either (google_not_found, naming the file).
• Only files picked through Google’s picker, or created by a step, are reachable (drive.file).
• A Google connection cannot be created by typing a token or from an MCP client: it is made by Google’s answer to a person who pressed the button, or by a person uploading a service-account key.
• The refresh token and the service-account private key are project secrets, so like every variable they are also visible to the project’s scripts as environment variables.