Google Tasks Integrator — API Design (2026-09-26)

Source: Tasks API v1 discovery doc (live fetch 2026-09-26).

Auth

OAuth2, per-user consent. Scopes: .../auth/tasks (read/write) or .../auth/tasks.readonly. Same renewable-OAuth pattern as the Asana connector at the protocol level: tokens stay encrypted on the customer's installation, never in the repo. Source OAuth lifecycle/BYO web-client intake does not establish native, headless, or complete sync acceptance.

Self-hosted connection modes and required edge cases are authoritative in Contract D of the master gap plan. Use connection/account/client-scoped credential references, not one provider-global newest token. User Tasks grants and optional administrator grants are separate; selecting a list restricts Flow Mesh, not Google's account-wide Tasks scope.

Resources (all CRUD present)

  • tasklists: list/get/insert/patch/update/delete
  • tasks: list/get/insert/patch/update/delete/move/clear

Sync mechanism: poll with updatedMin

The launch connector uses bounded polling, not an assumed push channel. Adding Cloud Pub/Sub alone does not establish a documented Tasks push subscription. Poll each selected list with updatedMin=<last sync>, showDeleted=true, showCompleted=true, and showHidden=true so tasks completed in first-party clients remain discoverable. Commit all relevant pages before advancing the cursor; use bounded overlap/reconciliation for retry and equal-timestamp boundaries. Prove this behavior across restarts.

Field mapping (Google Task ↔ bead)

Google Bead
title title
notes description
due (RFC3339) due date
status needsAction/completed open/closed
updated last-write-wins anchor
deleted=true delete/tombstone
parent/position subtask/order (phase 2)
assignmentInfo assignee (phase 2)

Conflict rule

Last-write-wins on updated, same as the Asana direction. A task edited on both sides between polls keeps the newer updated; the loser is logged as a sync receipt, never silently dropped. Equal/ambiguous ordering and field-ownership conflicts remain visible rather than guessed. Whether Google accepts conditional HTTP writes needs independent evidence; absence of If-Match in discovery query parameters proves nothing about HTTP header support.

Progress-card projection

Google Tasks is a first-class progress-card interface, not a later optional add-on. One parent task represents a card and child tasks represent steps where supported; otherwise the parent notes render the checklist while stable step identity remains in Flow Mesh. Updates edit existing tasks rather than creating duplicates. See the progress-card contract in 2026-09-26-FLOW-MESH-MASTER-GAP-PLAN.md.

Onboarding and provider edge-case acceptance

Contract D ONB-01 through ONB-44 supplies the complete acceptance matrix. Google-specific proofs must distinguish:

  • publisher app readiness vs BYO Web/Desktop client type and exact callback;
  • consumer and Workspace accounts, partial/read-only scopes, wrong-account selection, multiple connections, existing grants, refresh, and revocation;
  • Cloud API disabled vs Workspace Tasks disabled vs OAuth app blocked; an uncorroborated 403/404 is not sufficient to change organization policy;
  • explicit list selection/creation, pagination, duplicate names, missing lists, initial import, and remote-success/local-commit ambiguity;
  • credential success, read access, project binding, approved first-task proof, bidirectional sync, and human-visible delivery as separate states;
  • due date-only behavior; read-only assignment metadata is not a generic writable assignee; output-only parent/position responses do not prohibit supported insert/move hierarchy/order parameters;
  • clear hides completed tasks; deleting an assigned task can also delete its originating Docs/Chat task, requiring an explicit bounded preview;
  • unavailable or missing task deep links: show a verified supported list/web fallback without claiming every task has a stable URL;
  • cancellation/rebind/revoke cleanup affects only owned attempt objects, never unrelated tasks or organization-wide service settings.

Scope guard

Google Tasks + Asana are the current human task interfaces. No Linear/Jira work under this design; the generic progress-surface contract may support other interfaces later without changing core state.

Bringing Google Tasks live on a deployment (operator runbook)

This is the supported path from "connected: no" to a proven live round trip. It records the exact stopping points observed on the reference deployment so nobody re-derives them.

1. Provider authority must be reachable before anything else

Google does not expose a documented API for creating standard consumer OAuth clients (see 2026-09-27-FLOW-MESH-PORTABLE-AUTHORITY-BOOTSTRAP.md, "Google Tasks limits"). The supported route is the provisioning cascade, which drives console.cloud.google.com through a deployment-owned, loopback-only browser profile using config/provider-recipes/google-tasks-oauth-client.v1.json (operation oauth_client.create).

Start the profile and confirm the driver is live:

scripts/provider-console-browser.sh            # or FLOW_MESH_PROVIDER_BROWSER_MODE=headless
curl -sf http://127.0.0.1:9222/json/version    # CDP must answer

Observed boundary. A fresh profile navigated to https://console.cloud.google.com/auth/clients lands on accounts.google.com sign-in. The cascade therefore stops at the provider authority grant, not at a Flow Mesh defect. That grant is one of:

  • an authenticated Google Cloud console session for a principal allowed to create OAuth clients in the target project; or
  • Workspace domain-wide delegation for the Tasks scope, granted by the Workspace administrator (unattended afterwards).

Neither can be self-issued by the product. Record whichever was granted, and by whom, before claiming the provider is connected.

GET /api/providers/google-tasks/status reports authority_mode: disabled with configured: false whenever the encryptor is off, regardless of consent.

Check it with a deliberately invalid post:

curl -s -X POST -d 'client_json=' \
  http://127.0.0.1:8300/api/providers/google-tasks/client
  • 503 credential encryption is not configured → fix the secret first.
  • 400 invalid Google OAuth client JSON → encryption works; continue.

Known trap (fixed, retained for regression): a systemd unit using EnvironmentFile=-/etc/flow-mesh/<name>.env silently ignores a file the service user cannot read. On the reference deployment the file was root:root 0600 under User=wirebot, so FLOW_MESH_SECRET never loaded and every provider reported an ordinary "unconfigured" state. File-backed secrets belong to the service user, mode 0600, with a traversable ancestor. Tracked as flow-mesh-npetf (the missing loud signal).

# 3a. Supply the downloaded OAuth client JSON (never paste the secret in chat)
curl -s -X POST --data-urlencode "client_json@/secure/google-oauth-client.json" \
  http://127.0.0.1:8300/api/providers/google-tasks/client

# 3b. Complete consent through the bounded connect route
#     /providers/google-tasks/connect  (state + PKCE; callback /auth/google-tasks/callback)

# 3c. Prove liveness — this is the only accepted evidence
curl -s http://127.0.0.1:8300/api/providers/google-tasks/status
# {"authority_mode":"direct_oauth","configured":true,"status":"connected","renewable":true}

status: connected and renewable: true are both required. A connected but non-renewable credential cannot sustain sync and must not be reported as a finished connection.

4. Named failure signatures (do not conflate these)

Signature Meaning Not the same as
403 access_denied on a DWD JWT delegation grant missing or wrong scope API disabled
403 api_disabled / permission_denied on the Tasks API tasks.googleapis.com not enabled for the project delegation failure
AUTH_PERMISSION_DENIED on serviceusage.services.enable principal cannot enable APIs in that project product defect
console navigate → accounts.google.com no authenticated session or delegation recipe failure
provider_credential_unreadable credential reference path unreadable by the service user invalid credential

The integration join requires google-tasks-live: a deployment whose status endpoint reports connected and renewable. The acceptance test (internal/e2e, TestAtom_GoogleTasksLive) skips with the exact reason until FLOW_MESH_LIVE_BASE_URL points at such a deployment, so an unproven atom is never reported as a pass.

Consent needs a browser, a redirect URI, and a human. Refreshing needs only the OAuth client and a refresh token. When the account has already been authorized elsewhere — another tool, a migration, a prior installation — carry that grant over instead of re-running consent:

mesh connect google-tasks \
  --client-file /path/to/client.json \
  --token-file  /path/to/token.json \
  --config /data/flow-mesh/config.yaml

Both files are read, never echoed. --client-file accepts all three published client shapes (console installed/web wrappers or flat client_id/client_secret); the stored form is always flat, because that is what the service reads back before refreshing. --token-file accepts {"refresh_token":…} or {"token":{"refresh_token":…}}.

The command refreshes the grant, calls the Tasks API with the refreshed access token, and only then stores it. A dead, revoked, or non-renewable grant fails before anything is written — a stored grant is one that demonstrably works.

Output on success:

{"expires_at":"…","provider":"google_tasks","renewable":true,"status":"connected","verified":true}

Verify against the running service, not the command output:

curl -s <base>/api/providers/google-tasks/status
# {"authority_mode":"direct_oauth","configured":true,"provider":"google_tasks","renewable":true,"status":"connected"}
curl -s <base>/api/providers/google-tasks/lists
# discovery binds the remote list; newly_bound >= 1 on first run

Why this exists in the product

An installation that cannot complete a browser consent — headless server, locked console, restricted redirect URIs, or an account whose grant already exists elsewhere — otherwise cannot use Google Tasks at all. Import is the supported path for that case, and it is the same code path the consent callback writes through, so both land one encrypted credential with one shape.

Never pass a secret as a command-line argument or print a token file to check it: --client-file/--token-file point at files, and the command prints structure and validity, never values.

Generated from the Flow Mesh repository by scripts/build-docs-site.sh. If a page is wrong here, the file it was rendered from is wrong.