Appearance
SaaS Connector Administration
Overview
SaaS connectors let your organization connect third-party tools (Rippling, Slack, Jira, Salesforce) to enrich the AI's memory with organizational context. This guide covers administration tasks: enabling connectors, managing connections, configuring access control, monitoring health, and handling data lifecycle.
Prerequisites
- Admin or Owner role in your organization
- Personal or higher subscription tier
SAAS_CONNECTORS_ENABLED=truein deployment configuration (instance-level kill switch)- For Rippling:
RIPPLING_CLIENT_IDandRIPPLING_CLIENT_SECRETconfigured - For Merge HRIS:
MERGE_API_KEYconfigured
Enabling Connectors
Two gates must be active:
- Instance-level:
SAAS_CONNECTORS_ENABLED=truein environment configuration (deployment admin controls this) - Tier-level: The
saas_connectorsfeature flag gates access by subscription tier (Personal+)
To verify: navigate to Settings → SaaS Integrations. If the tab is visible but shows a tier-gate message, upgrade your subscription. If the tab is missing entirely, the instance-level setting is disabled.
Connecting a SaaS Tool
- Navigate to Settings → SaaS Integrations
- Click Connect on the desired connector
- Review the consent dialog — it explains what data will be accessed and what PII fields are filtered
- Click Connect to [Provider] — this opens an OAuth popup
- Authorize GhostAI in the provider's interface
- The popup closes and the initial sync begins automatically
The consent timestamp is stored in saas_connections.consent_accepted_at for GDPR/CCPA compliance.
Managing Connections Across Your Organization
Admins can view all connections in the organization via the admin panel:
- API:
GET /api/connectors/admin/connections - UI: Settings → SaaS Integrations → Admin view (visible to admin/owner roles)
The admin view shows: connector name, who connected it, health status, last sync time, record count, and visibility scope.
Access Control Configuration
Each connection has a configurable visibility scope that determines who sees the synced data in their AI sessions:
| Scope | Description | Memory Scope |
|---|---|---|
| Organization-wide (default) | All org members see this data | cloud |
| Group-restricted | Only members of a specific group | group |
| User-only | Only the connecting user | user |
To change: PUT /api/connectors/connections/{id}/visibility (admin-only) or use the Settings UI in the connection detail view.
Impact: When set to Group-restricted, only members of the specified group will have connector-sourced memories injected into their AI context window.
Audit Log Events
All connector operations are logged. Filter by these event types in the AI Audit Log:
| Event | Description | Key Fields |
|---|---|---|
connector.connected | SaaS tool connected via OAuth | connector_id, provider_account_name |
connector.disconnected | Connection revoked, data cascade-deleted | connector_id, records_deleted, memories_deleted |
connector.sync_started | Sync job initiated | connector_id, trigger (manual/scheduled/webhook) |
connector.sync_completed | Sync job finished successfully | connector_id, records_synced, duration_ms |
connector.sync_failed | Sync job failed | connector_id, error, retry_count |
connector.webhook_received | Inbound webhook processed | connector_id, event_type, records_upserted |
connector.action_executed | AI invoked a connector action | connector_id, action_name, success |
connector.visibility_changed | Access control scope updated | connector_id, old_scope, new_scope |
connector.health_degraded | Connection health status worsened | connector_id, old_status, new_status |
Health Monitoring
GhostAI proactively monitors connection health every 15 minutes (configurable via CONNECTOR_HEALTH_CHECK_INTERVAL_MINUTES).
Health Statuses
| Status | Meaning | Action |
|---|---|---|
| Healthy | Token valid, last sync succeeded | None required |
| Warning | Token expires within 24 hours, or last sync had non-fatal errors | Re-authorize soon |
| Error | Last 3 syncs failed, or API unreachable | Investigate and re-authorize |
| Expired | OAuth token has expired | Re-authorize immediately |
Notifications
When a connection's health degrades, org admins receive a notification via the existing notification service. Example: "Your Rippling connection token expires in 24 hours. Re-authorize to prevent sync interruptions."
Admin Health Overview
GET /api/connectors/admin/health returns health status for all org connections.
Webhook Setup for Real-Time Sync
Business+ Feature
Real-time webhook sync requires a Business or Enterprise subscription.
Each connection gets a unique, unguessable webhook URL:
POST /api/connectors/webhooks/{connector_id}/{webhook_secret}To configure:
- Open the connection detail view
- Navigate to the Webhooks tab
- Copy the webhook URL
- In your SaaS tool's webhook settings, paste the URL and select the events to send
The Webhooks tab also shows: events received count, last received timestamp, and enable/disable toggle.
Rippling Webhook Setup
- In Rippling Admin → Platform → Webhooks
- Add a new webhook with the URL from GhostAI
- Select events:
employee.created,employee.updated,employee.terminated - Save — Rippling will send a test event
Revoking Connections & Data Cleanup
When a connection is revoked (via DELETE /api/connectors/connections/{id} or the Disconnect button):
- Connection status set to
revoked - Webhook configurations disabled
- All connector records soft-deleted (
deleted_atset) - All associated AI memories permanently deleted
- Audit log entry created with record/memory counts
WARNING
Before disconnecting, consider exporting connector records if you need them for compliance. Use the existing data export service.
Environment Variables Reference
| Variable | Description | Required | Default |
|---|---|---|---|
SAAS_CONNECTORS_ENABLED | Master kill switch for SaaS connectors | Yes | false |
RIPPLING_CLIENT_ID | Rippling OAuth app client ID | For Rippling | — |
RIPPLING_CLIENT_SECRET | Rippling OAuth app client secret | For Rippling | — |
MERGE_API_KEY | Merge.dev API key for unified HRIS | For Merge | — |
CONNECTOR_SYNC_INTERVAL_MINUTES | Scheduled sync interval | No | 60 |
CONNECTOR_HEALTH_CHECK_INTERVAL_MINUTES | Health check interval | No | 15 |
CONNECTOR_MEMORY_SYNC_ENABLED | Whether to bridge records to AI memory | No | true |
CONNECTOR_WEBHOOK_BASE_URL | Public URL for webhook callbacks | No | base_url |