Buffaly Logo
Browse docs Menu

Start here

Docs home Install Buffaly Install on Windows Install on Linux Install on Mac Quickstart How-to library

Learn Buffaly

What Buffaly is User guide Core concepts Coming from other agents Memory and skills

Build and extend

Add a prompt skill Add a ProtoScript skill Add a C# DLL tool Add a model provider Skills, services, and tools ProtoScript services

Operate

Sessions and long-running work Session anatomy Plan, Scratch, and Tasks Session artifacts Session timeline Compaction

Reference

Ontology and ProtoScript Providers and authentication Web modules and UI Diagnostics & recovery Safety rules Secrets handling SmartPatch
Integration how-to

How to connect Google Workspace to Buffaly

Google Workspace access is configured from the Google Workspace accounts page in the Buffaly web UI. Use it to choose an authentication mode, connect or reconnect an account, validate the saved connection, and confirm whether the connection is durable enough for future work.

Start with the account and workspace you want Buffaly to use for Docs, Sheets, Gmail drafts, Calendar, Drive, or Chat workflows. Then verify a harmless read before asking Buffaly to draft, edit, send, or update anything.

Choose the right authentication mode

ModeUse whenWhat it means
Desktop app clientBuffaly is installed locally or used like a local desktop app.Buffaly uses a Google OAuth desktop client and a local callback such as /gauth.
Custom web clientBuffaly is hosted for a team or production environment.Buffaly uses a Google OAuth web client configured for that hosted domain and redirect URI.

The OAuth client ID configures the application. The user-specific credential that must be protected is the OAuth token saved after you grant access, especially the refresh token.

Desktop app client mode

Desktop mode is intended to make local installs easier. It avoids requiring every local user to create a Google web application before connecting an account.

  1. Open the Google Workspace accounts page in Buffaly.
  2. Choose desktop app client mode when the install offers it.
  3. Start the Google sign-in flow.
  4. Grant only the access needed for the workflows you plan to use.
  5. Return to Buffaly and confirm the account appears.
  6. Validate the account and confirm it shows Refresh token saved.

Custom web client mode

Custom web mode is for hosted Buffaly instances. The Google Workspace feature must contain a web OAuth client ID, client secret, and redirect URI that match the hosted site.

  • The Google Cloud OAuth client must be configured as a web application.
  • The redirect URI must match the Buffaly instance users will open.
  • If Google reports a redirect URI mismatch, fix the Google Cloud OAuth client configuration or use the correct Buffaly instance URL.
  • After sign-in, validate the account and confirm durable refresh-token access.

Refresh tokens and saved accounts

A successful connection should save a refresh token. The refresh token lets Buffaly get new short-lived access tokens later without asking you to sign in again every time.

Good state

The account appears, validation succeeds, and the page reports Refresh token saved.

Reconnect state

If the account exists but no refresh token is saved, use reconnect instead of assuming the connection is durable.

Use saved account management when you need to validate, reconnect, or remove an account. Do not paste OAuth tokens into chat.

Scopes, manual completion, and how to tell it worked

Google scopes decide what Buffaly can request: Drive and Docs for document work, Sheets for spreadsheet work, Gmail for mail drafts or reads, Calendar for calendar workflows, and Chat only when chat integration is configured. Grant only the scopes needed for the workflows you plan to use.

If the browser flow cannot complete automatically, use the manual completion path shown by the Google Workspace accounts page and then return to saved account management to validate or reconnect the account.

  • The account appears on the page with the expected email address.
  • Validation succeeds and reports durable refresh-token access.
  • A harmless read, such as listing a known Drive file or opening a test sheet, succeeds.
  • Saved account management can validate, reconnect, or remove the account when needed.

What Buffaly asks Google for, durability, and security notes

Buffaly asks Google for the scopes needed by the configured workflow: Drive and Docs for document work, Sheets for spreadsheet work, Gmail for mail workflows, Calendar for calendar workflows, and Chat only when chat integration is configured.

Durable access depends on a saved refresh token. If validation succeeds but no refresh token is saved, reconnect the account before expecting future unattended or long-running work to succeed.

  • Do not paste OAuth tokens into chat.
  • Use the account management page to validate, reconnect, or remove accounts.
  • Verify with a harmless read before asking Buffaly to draft, update, send, or delete anything.

Common issues

The page still looks disconnected after sign-in

Refresh the accounts page and validate the account. If the refresh token is missing, reconnect.

Google says the redirect URI is invalid

You are likely using custom web mode with a redirect URI that does not match the Google Cloud OAuth client.

The account says reconnect required

The saved token may be missing, revoked, expired, or tied to old OAuth settings. Reconnect the account through the UI.

You do not see the Google Workspace page

The feature may not be enabled in this install. Ask Buffaly to show this install's capabilities and configured integrations.

After it works

Ask Buffaly to verify one harmless read from the account, then teach it the Docs, Sheets, folders, or workflows you want to refer to by name.