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/deletetasks: 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)
| 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;
duedate-only behavior; read-only assignment metadata is not a generic writable assignee; output-onlyparent/positionresponses do not prohibit supportedinsert/movehierarchy/order parameters;clearhides 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.
2. Credential encryption must be enabled, or consent cannot be stored
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).
3. Store the client, consent, then prove it
# 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.
Importing an existing renewable grant (no consent round trip)
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.