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-registryat startup - Orchestrator discovers endpoints dynamically via
CAPABILITY_REGISTRY_URL - Orchestrator does not use an
EGRESS_GOOGLE_WORKSPACE_URLcode path forservice_call
Outbound Authentication (Google)¶
Auth is service-account based (OAuth 2.0 JWT bearer grant):
- Orchestrator sends connection fields (
service_account_key,impersonate_user,scopes) on theservice_call(after secret resolution / credential isolation). - Service signs JWT with the service-account private key.
- Service exchanges JWT at Google token endpoint for access token.
- Token is cached in-process per
(client_email, scopes, impersonate_user). - 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 /healthzGET /readyzGET /internal/capabilities