Skip to content

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=true in deployment configuration (instance-level kill switch)
  • For Rippling: RIPPLING_CLIENT_ID and RIPPLING_CLIENT_SECRET configured
  • For Merge HRIS: MERGE_API_KEY configured

Enabling Connectors ​

Two gates must be active:

  1. Instance-level: SAAS_CONNECTORS_ENABLED=true in environment configuration (deployment admin controls this)
  2. Tier-level: The saas_connectors feature 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 ​

  1. Navigate to Settings → SaaS Integrations
  2. Click Connect on the desired connector
  3. Review the consent dialog — it explains what data will be accessed and what PII fields are filtered
  4. Click Connect to [Provider] — this opens an OAuth popup
  5. Authorize GhostAI in the provider's interface
  6. 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:

ScopeDescriptionMemory Scope
Organization-wide (default)All org members see this datacloud
Group-restrictedOnly members of a specific groupgroup
User-onlyOnly the connecting useruser

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:

EventDescriptionKey Fields
connector.connectedSaaS tool connected via OAuthconnector_id, provider_account_name
connector.disconnectedConnection revoked, data cascade-deletedconnector_id, records_deleted, memories_deleted
connector.sync_startedSync job initiatedconnector_id, trigger (manual/scheduled/webhook)
connector.sync_completedSync job finished successfullyconnector_id, records_synced, duration_ms
connector.sync_failedSync job failedconnector_id, error, retry_count
connector.webhook_receivedInbound webhook processedconnector_id, event_type, records_upserted
connector.action_executedAI invoked a connector actionconnector_id, action_name, success
connector.visibility_changedAccess control scope updatedconnector_id, old_scope, new_scope
connector.health_degradedConnection health status worsenedconnector_id, old_status, new_status

Health Monitoring ​

GhostAI proactively monitors connection health every 15 minutes (configurable via CONNECTOR_HEALTH_CHECK_INTERVAL_MINUTES).

Health Statuses ​

StatusMeaningAction
HealthyToken valid, last sync succeededNone required
WarningToken expires within 24 hours, or last sync had non-fatal errorsRe-authorize soon
ErrorLast 3 syncs failed, or API unreachableInvestigate and re-authorize
ExpiredOAuth token has expiredRe-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:

  1. Open the connection detail view
  2. Navigate to the Webhooks tab
  3. Copy the webhook URL
  4. 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 ​

  1. In Rippling Admin → Platform → Webhooks
  2. Add a new webhook with the URL from GhostAI
  3. Select events: employee.created, employee.updated, employee.terminated
  4. 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):

  1. Connection status set to revoked
  2. Webhook configurations disabled
  3. All connector records soft-deleted (deleted_at set)
  4. All associated AI memories permanently deleted
  5. 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 ​

VariableDescriptionRequiredDefault
SAAS_CONNECTORS_ENABLEDMaster kill switch for SaaS connectorsYesfalse
RIPPLING_CLIENT_IDRippling OAuth app client IDFor Rippling—
RIPPLING_CLIENT_SECRETRippling OAuth app client secretFor Rippling—
MERGE_API_KEYMerge.dev API key for unified HRISFor Merge—
CONNECTOR_SYNC_INTERVAL_MINUTESScheduled sync intervalNo60
CONNECTOR_HEALTH_CHECK_INTERVAL_MINUTESHealth check intervalNo15
CONNECTOR_MEMORY_SYNC_ENABLEDWhether to bridge records to AI memoryNotrue
CONNECTOR_WEBHOOK_BASE_URLPublic URL for webhook callbacksNobase_url

SOC 2 Type II Certified | BAA Available | HIPAA-Ready