Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.encoreos.io/llms.txt

Use this file to discover all available pages before exploring further.

Audience: Tenant admins / platform operators connecting a Google Workspace tenant. Permissions required: pf.google_workspace.manage and org_admin system role. Pre-reqs: Signed Google Workspace BAA (Business Associate Agreement) for any PHI-capable capability.

​
1. Provision the Google service account

  1. In Google Cloud Console, create a project for the EncoreOS connector.
  2. Enable APIs: Admin SDK, Gmail, Calendar, Drive, Chat, Licensing, Reports.
  3. Create a service account; download the JSON private key.
  4. In Workspace Admin Console → Security → API controls → Domain-wide Delegation, authorize the service account’s client ID with the least-privilege scopes for the capabilities you intend to enable. The exact scope list per capability is in CAPABILITY_SCOPES inside supabase/functions/_shared/google-workspace-client.ts.
  5. Designate a Workspace delegated subject (a real super-admin email) — DWD impersonates this user for all admin reads/writes.

​
2. Store credentials in PF-76 Credential Vault

Never paste the JSON key into Supabase env, table columns, or chat. Use the credential vault wrapper:
  1. In Settings → Integrations → Google Workspace, click “Connect”.
  2. Paste the service account JSON; the UI hands it directly to the pf_store_credential RPC.
  3. The connection row in pf_google_workspace_connections only stores credential_vault_ref (an opaque ID).

​
3. Capability flags

On the connection row, enable only the capabilities the tenant actually needs:
ColumnCapabilityPHI-capable
capability_directory_enabledUser provisioning / suspendNo
capability_gmail_enabledOutbound email sendYes
capability_calendar_enabledCalendar events / Meet linksYes
capability_drive_enabledDrive metadata / mappingsYes
capability_chat_enabledChat notificationsYes (PHI blocked in MVP)
capability_licensing_enabledLicense Manager assign / revokeNo
capability_reports_enabledAudit Reports ingestionNo

​
4. BAA attestation (required before PHI-capable use)

After signing the Google Workspace BAA:
  1. Org admin opens Settings → Integrations → Google Workspace → Compliance.
  2. Records BAA reference (Google contract ID), attesting user, and date.
  3. Backend writes baa_attested_at and baa_attested_by on the connection.
Until both BAA attestation and the capability flag are set, all Gmail / Calendar / Drive / Chat operations fail closed.

​
5. Test the connection

Call the per-capability health check from the UI (“Test connection”) or directly: 
curl -X POST "$SUPABASE_URL/functions/v1/google-workspace-test-connection" \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d '{"connection_id":"<uuid>"}'
The response lists pass/fail per capability. Failures include a sanitized reason_code (e.g., scope_missing, baa_required, domain_mismatch) — never raw Google error bodies.

​
6. Migrate from legacy Gmail (GMAIL_SERVICE_ACCOUNT_JSON)

The shared email-provider.ts adapter prefers a PF-101 connection when one exists for the tenant; otherwise it falls back to the legacy env var. Per-tenant migration:
  1. Connect Workspace + attest BAA + enable Gmail capability (steps 1–4).
  2. Send a test email through any platform notification flow.
  3. Once smoke-tested, the platform team can remove the tenant’s reliance on GMAIL_SERVICE_ACCOUNT_JSON. Do not delete the env until every tenant has migrated.

​
7. Operations & monitoring

  • Sync runs: every provision / offboard / reconcile / Reports pull writes a row to pf_google_workspace_sync_runs. Filter by status = 'failed' for triage.
  • Directory reconcile: scheduled cron compares HR employees vs Workspace suspended state and records drift.
  • Audit: Reports ingestion writes hashed-actor rows to pf_audit_log for HIPAA audit trail.

​
8. Troubleshooting

SymptomLikely causeFix
baa_requiredCapability is PHI-capable but BAA not attestedComplete §4
scope_missingDWD authorization missing for capability scopeRe-authorize service account in Workspace Admin Console with required scopes
domain_mismatchGmail sender domain ≠ primary_domainUse a sender on the connected domain
credential_unavailablePF-76 vault ref invalid / rotatedReconnect the service account JSON