Skip to content

Egress Google Workspace

Responsibility

Google Workspace capability provider for Gmail, Calendar, and Drive. Workflows call it via service_call and the capability registry — same pattern as Weatherstack/Postgres.

Capabilities (from engine/services/google-workspace/app/main.py):

Capability Path
egress.google_workspace.gmail.list /gmail/list
egress.google_workspace.gmail.read /gmail/read
egress.google_workspace.gmail.send /gmail/send
egress.google_workspace.gmail.reply /gmail/reply
egress.google_workspace.calendar.list_events /calendar/list-events
egress.google_workspace.calendar.create_event /calendar/create-event
egress.google_workspace.drive.list_files /drive/list-files
egress.google_workspace.drive.upload /drive/upload
google_workspace.connection connection type

Additional HTTP routes may exist on the service (e.g. update-event, free-busy, download); prefer capabilities listed in /internal/capabilities / registry for workflow design.

Architecture

This is a capability provider (see Deploy integration contract and Contract 17):

  • Registers with capability-registry at startup
  • Orchestrator discovers endpoints dynamically via CAPABILITY_REGISTRY_URL
  • Orchestrator does not use an EGRESS_GOOGLE_WORKSPACE_URL code path for service_call

Outbound Authentication (Google)

Auth is service-account based (OAuth 2.0 JWT bearer grant):

  1. Orchestrator sends connection fields (service_account_key, impersonate_user, scopes) on the service_call (after secret resolution / credential isolation).
  2. Service signs JWT with the service-account private key.
  3. Service exchanges JWT at Google token endpoint for access token.
  4. Token is cached in-process per (client_email, scopes, impersonate_user).
  5. API requests use Authorization: Bearer <access_token>.

Connection Model

Use google_workspace connection type:

name: google-workspace-calendar
type: google_workspace
service_account_key: "$secret:google-workspace-sa-key"
impersonate_user: "workflow-runner@example.com"  # optional
scopes:
  - https://www.googleapis.com/auth/calendar

Secrets Guidance

  • Store full service-account JSON in runtime secrets.
  • Reference via $secret:<name> in connection YAML.
  • Avoid inline private keys in Git-managed files.

Required IAM / Workspace Setup

  • Create Google Cloud service account with required API access.
  • Enable target APIs (Gmail, Calendar, Drive) in project.
  • If acting as domain user, configure domain-wide delegation and set impersonate_user.
  • Grant least-privilege scopes per connection.

Example workflow step

- id: list_mail
  type: service_call
  capability_name: egress.google_workspace.gmail.list
  capability_version: "^1.0"
  path: /gmail/list
  connection: google-workspace-calendar
  payload: |
    {
      "mailbox": "me",
      "max_results": 10
    }
  timeout_seconds: 60

Deploy

  • Image: meshflows/egress-google-workspace
  • Deployment: egress-google-workspace

Health

  • GET /healthz
  • GET /readyz
  • GET /internal/capabilities