Google Sheets

Proxy for the Google Sheets v4 REST API. Dual auth by design — like drive and calendar, the typical production setup runs the connector in one of two modes per managed resource:

• idp_passthrough mode for human users who want an agent to read or edit spreadsheets they already own. Each request carries the caller's own OAuth grant.
• google_sa mode (Workspace service account with domain-wide delegation) for headless workflows that read or write shared/team spreadsheets on a fixed identity's behalf.

Overview

Typical uses:

• An agent reads a forecast tab and summarizes the numbers (get_values, batch_get_values).
• A reporting bot appends rows to a tracking sheet (append_values) or rewrites a range (update_values).
• A workflow spins up a fresh spreadsheet, adds a tab, and copies a template sheet into it (create_spreadsheet, batch_update, copy_sheet).

Two upstream-shape notes specific to Sheets:

• No list endpoint. The Sheets API can't enumerate spreadsheets; discover spreadsheet IDs via the Google Drive connector (filter on mimeType = 'application/vnd.google-apps.spreadsheet'), then operate on the ID here.
• Deletes go through batch_update. Deleting a sheet, row, column, or range is a deleteSheet/deleteDimension/deleteRange request object on batch_update; deleting an entire spreadsheet file is the Drive connector's job. update_values/append_values carry valueInputOption in the query string (RAW vs USER_ENTERED), and ranges use A1 notation (Sheet1!A1:C10).

Default policy

The connector ships policy/sheets.rego (package pbac.connectors.identos.google_sheets). It enforces:

1. IdP-routing subject obligation

subject_obligations contains obl if {
    input.resource.type == "urn:connector:identos:google-sheets"
    input.connector.upstream_auth.type == "idp_passthrough"
    input.subject.idp_provider != "google"
    obl := { "type": "require_authn_at", "idp": "google", ... }
}

Same pattern as google-drive/gmail — a caller from a non-Google session gets a step-up obligation before any passthrough Sheets call succeeds.

2. blocked_spreadsheet_ids deny (read + write)

A "nuclear" deny: the spreadsheet is off-limits to this connector entirely, reads and writes both blocked. Use it for a sensitive sheet the service account happens to have access to but that shouldn't be exposed to LLM-driven workflows.

3. read_only_spreadsheet_ids deny (write only)

Listed spreadsheets allow GET but deny the mutating routes (update_values, append_values, clear_values, batch_clear_values, batch_update, copy_sheet). Reads still work — useful for agents that should surface but not modify a shared sheet.

Supplying operator data

curl -X PUT http://localhost:8080/admin/policy/data/pbac/operator/connectors/identos.google-sheets \
  -H "X-Admin-API-Key: $PBAC_ADMIN_API_KEY" \
  -d '{
    "blocked_spreadsheet_ids":   ["1AbciSensitiveSheetId"],
    "read_only_spreadsheet_ids": ["1XyzSharedReportId"]
  }'

Scope model

	Scope	Used for
PBAC scopes (internal)	sheets:read, sheets:write	Route authorization
Upstream OAuth scopes	spreadsheets	Google-side grant the user consents to (idp_passthrough mode); the service-account flow uses the same scope on the SA

See Google Workspace: multi-connector setup for how sheets' scopes compose with drive, gmail, and calendar on a single Google IdP.

Manifest reference

• ID: identos.google-sheets
• Version: 1.0.0
• Resource type: urn:connector:identos:google-sheets

Supported auth modes

Type	Details
idp_passthrough	requires IdP google
google_sa	setup fields: sa_key_env, domain

Setup fields

ID	Label	Default	Secret?	Notes
base_url	API base URL	https://sheets.googleapis.com	no	—
upstream_auth.type	Authentication	idp_passthrough	no	idp_passthrough forwards each user's own Google OAuth token (recommended). google_sa uses a Workspace service account with domain-wide delegation impersonating a fixed user.
sa_key_env	Service account key	—	yes	Pick a secret containing the service-account JSON. Required only for the google_sa auth mode. / shown when upstream_auth.type == 'google_sa'
domain	Workspace domain	—	no	placeholder: example.com / Required only for the google_sa auth mode. / shown when upstream_auth.type == 'google_sa'

Scopes

Scope
sheets:read
sheets:write

Routes

Method	Pattern	Scope	Resource template
POST	/v4/spreadsheets	sheets:write	—
GET	/v4/spreadsheets/{spreadsheet_id}	sheets:read	sheets://{{spreadsheet_id}}
GET	/v4/spreadsheets/{spreadsheet_id}/values/{range}	sheets:read	sheets://{{spreadsheet_id}}
GET	/v4/spreadsheets/{spreadsheet_id}/values:batchGet	sheets:read	sheets://{{spreadsheet_id}}
PUT	/v4/spreadsheets/{spreadsheet_id}/values/{range}	sheets:write	sheets://{{spreadsheet_id}}
POST	/v4/spreadsheets/{spreadsheet_id}/values/{range}:append	sheets:write	sheets://{{spreadsheet_id}}
POST	/v4/spreadsheets/{spreadsheet_id}/values/{range}:clear	sheets:write	sheets://{{spreadsheet_id}}
POST	/v4/spreadsheets/{spreadsheet_id}/values:batchClear	sheets:write	sheets://{{spreadsheet_id}}
POST	/v4/spreadsheets/{spreadsheet_id}/sheets/{sheet_id}:copyTo	sheets:write	sheets://{{spreadsheet_id}}
POST	/v4/spreadsheets/{spreadsheet_id}:batchUpdate	sheets:write	sheets://{{spreadsheet_id}}

MCP tools

Name	Scope	Description
create_spreadsheet	sheets:write	Create a new spreadsheet. Pass the Sheets Spreadsheet resource body (e.g. {properties:{title}, sheets:[...]}).
get_spreadsheet	sheets:read	Get a spreadsheet's metadata and (optionally) cell data. Use the includeGridData flag sparingly — it can be large.
get_values	sheets:read	Read values from a single A1 range (e.g. "Sheet1!A1:C10").
batch_get_values	sheets:read	Read values from multiple A1 ranges in one call.
update_values	sheets:write	Overwrite values in an A1 range. Pass values as a 2-D array; set valueInputOption (RAW or USER_ENTERED).
append_values	sheets:write	Append rows after the last row of a table within the given A1 range.
clear_values	sheets:write	Clear values (not formatting) from a single A1 range.
batch_clear_values	sheets:write	Clear values from multiple A1 ranges in one call.
copy_sheet	sheets:write	Copy a single sheet from this spreadsheet into another spreadsheet.
batch_update	sheets:write	Apply one or more structural updates (add/delete sheet, insert/delete rows & columns, formatting, etc.) via Sheets batchUpdate request objects. This is also how you DELETE sheets/rows/columns/ranges.

Operator data schema

Keys the operator can supply under data.pbac.operator.connectors["identos.google-sheets"].* — consumed by the connector's policy.

Key	Type	Description
blocked_spreadsheet_ids	array	Spreadsheet IDs that are off-limits to this connector — reads and writes both denied.
read_only_spreadsheet_ids	array	Spreadsheet IDs where writes (update/append/clear/batchUpdate/copyTo) are denied regardless of the caller's scope. Reads still work.