Agent auth flow feedback: interactive vs headless login paths

[jpoehnelt-bot]

Hi folks — sharing concrete feedback after trying to run real integration tests with gws from an agent environment.

What worked well

• Install and discovery are clear (gws --help)
• gws auth status is very useful (project, config paths, credential presence)
• gws auth setup gives actionable project/client setup guidance
• API errors were generally useful (401 no credentials, 403 insufficient scopes)

What was confusing for agent/headless usage

1. No creds present → Sheets call failed with 401 (expected)
2. Tried GOOGLE_WORKSPACE_CLI_TOKEN from gcloud auth print-access-token → call reached API but failed with 403 insufficient authentication scopes
3. gws auth login uses browser + localhost callback, which is awkward in headless/agent sessions

Suggestions

1. Add docs section: "Interactive developer login vs agent login" with a decision tree
2. Add gws auth login --device (device code flow) for headless use
3. Add gws auth doctor to validate:
   • credentials present
   • token scopes match requested service
   • required APIs enabled
   • exact remediation commands
4. Improve 403 insufficient scopes hints to include likely missing scopes based on command context
5. Add an "agent bootstrap" snippet (env vars + minimal scopes + smoke test)

Key elements extracted from related work

Path selection (interactive vs headless)

• Issue Support --port and --no-browser flags for gws auth login on remote/headless machines #210 (closed): proposed explicit flags for remote/headless usage:
  • --port <PORT> for fixed callback port (HTTPPortRedirect) to support stable SSH port-forwarding
  • --no-browser interactive copy/paste code flow (InstalledFlowReturnMethod::Interactive)
  • URL: Support --port and --no-browser flags for gws auth login on remote/headless machines #210
• PR feat(auth): add --no-localhost flag to gws auth login #231 (closed): implemented headless-style path via --no-localhost
  • Uses interactive auth code entry flow instead of localhost callback
  • Includes parsing improvements for pasted callback/code and test coverage updates
  • URL: feat(auth): add --no-localhost flag to gws auth login #231

Scope selection UX

• Issue Redesign scope picker: service-first UX with API-enabled badges #234 (closed): service-first scope picker proposal
  • Choose services instead of raw scopes
  • Show API-enabled badges, service descriptions, and scope count/risk signals
  • Warn (don’t hard-block) when a service API isn’t enabled yet
  • URL: Redesign scope picker: service-first UX with API-enabled badges #234
• PR feat(auth): redesign scope picker to show services instead of raw scopes #241 (closed): implemented service-first picker
  • Groups scopes by service
  • Adds templates (recommended/read-only/full)
  • Added a custom path fallback and tightened least-privilege behavior in custom selection
  • URL: feat(auth): redesign scope picker to show services instead of raw scopes #241

Active bug still open

• Issue gws auth login -s chat does not request Chat API OAuth scope #236 (open): gws auth login -s chat does not request a Chat OAuth scope
  • Leads to insufficient authentication scopes for Chat operations after login
  • URL: gws auth login -s chat does not request Chat API OAuth scope #236

Happy to test a revised flow again and report back with a full end-to-end Sheets integration run (create/write/batchUpdate/readback).

[jpoehnelt-bot]

Plan A — Minimal patch (fastest)

Goal: remove major headless friction with the smallest change set.

• Keep current localhost callback flow as default
• Keep --no-localhost for interactive code-entry auth
• Clarify docs for when to use default vs --no-localhost
• Fix gws auth login -s chat does not request Chat API OAuth scope #236 (chat scope missing in -s mapping) as a separate bugfix

Pros: quickest to stabilize, low regression risk.
Cons: no full device-code flow; users still paste codes in some setups.

[jpoehnelt-bot]

Plan B — Headless-first auth matrix

Goal: make auth path selection explicit and predictable across local/devbox/container/CI environments.

• Introduce explicit mode flags (default localhost, no-localhost interactive, optional fixed-port mode)
• Print runtime decision text (e.g., "Selected auth mode: ... because ...")
• Add gws auth doctor preflight for credentials, scopes, and API enablement
• Ensure every service alias maps to at least one OAuth scope (covers gws auth login -s chat does not request Chat API OAuth scope #236-class bugs)

Pros: clearest UX for agents and remote users.
Cons: larger implementation and test surface.

[jpoehnelt-bot]

Plan C — Scope UX hardening + incremental consent

Goal: improve the scope-selection journey and reduce re-login loops.

• Build on the service-first picker from feat(auth): redesign scope picker to show services instead of raw scopes #241
• Show API-enabled status clearly with warnings (not hard blocks)
• Add incremental scope grant support (e.g., gws auth add-scope or equivalent)
• Add post-login scope validation with actionable remediation
• Keep auth transport/path changes minimal

Pros: strongest scope ergonomics and least-privilege workflow.
Cons: does not fully solve headless path selection by itself.

[jpoehnelt-bot]

Plan D — Unified auth overhaul (comprehensive)

Goal: provide one cohesive auth system for both developers and agents.

• Implement full auth mode set (localhost, no-localhost interactive, optional device-code if feasible)
• Keep service-first scope picker and add incremental scope upgrades
• Add gws auth doctor plus richer 401/403 diagnostics with scope hints
• Publish an "Agent setup" quickstart with non-interactive-friendly examples

Pros: most complete long-term solution for mixed human + agent use.
Cons: largest scope; needs phased rollout and careful QA.