Skip to main content

Apple iCloud Drive Connector

The Apple iCloud Drive connector is a governed, read-only integration that imports and continuously syncs content from Apple iCloud Drive into the Keeptrusts Knowledge Base. Because Apple does not provide a public OAuth API for iCloud, this connector uses an Apple Bridge agent running on a macOS device that has access to the target iCloud account. Connector-backed files surface sync health in the Knowledge Base file inspector and support agent, task, and runner bindings.

Use this page when​

  • You are setting up an Apple iCloud Drive connector in Keeptrusts for the first time.
  • You need to understand the bridge runtime architecture for Apple connectors.
  • You need to troubleshoot connectivity between the Keeptrusts API service and the Apple bridge.
  • You want to understand how continuous sync works for iCloud Drive files.
  • You are a platform operator deploying and registering the Apple Bridge agent for your organization.

Primary audience​

  • Primary: Technical Engineers
  • Secondary: AI Agents, Technical Leaders

Prerequisites​

  • Access to the Connectors page in the Keeptrusts console.
  • The Apple Bridge agent installed on a macOS device that can access the target iCloud Drive content.
  • Confirmation from your platform operator that Apple connector support is enabled for your organization.
  • An Apple ID with access to the iCloud Drive files you want to import.
  • macOS permissions granted on the bridge host for Full Disk Access and iCloud availability.

Bridge runtime architecture​

Apple iCloud Drive does not expose a public OAuth API for third-party integrations. Keeptrusts uses a bridge agent on macOS to handle Apple authentication and relay file content to the Keeptrusts API service.

Keeptrusts API service
    │
    │  bridge registration, heartbeat, and event sync
    ▼
Apple Bridge agent on macOS  ←→  Apple iCloud Drive

The bridge agent:

  • authenticates with Apple iCloud on the macOS host
  • registers itself with Keeptrusts and reports health through heartbeat events
  • sends iCloud Drive change events so Keeptrusts can keep sync state current
  • never forwards Apple credentials to Keeptrusts — credentials stay on the bridge host

This architecture keeps Apple credentials on the bridge host. Keeptrusts only works with the registered bridge session and its reported health.

Setup steps​

Step 1: Install and register the Apple Bridge agent​

  1. Install or launch the Apple Bridge agent on a macOS device with access to the target iCloud account.
  2. Sign the macOS host into the Apple ID that owns the iCloud Drive content you want to import.
  3. Register the bridge agent with the Keeptrusts organization using your deployment's Apple bridge onboarding flow.
  4. Confirm the bridge session shows healthy status and the required macOS permissions are granted.

Step 2: Create the connector in the console​

  1. Open Connectors in the Keeptrusts console.
  2. Click Add connector.
  3. Enter a connector Name.
  4. Choose Apple iCloud Drive as the provider.
  5. Choose the connector Scope.
  6. Click Create connector.
  7. Open the connector detail page.
  8. Click Authorize.
  9. Keeptrusts verifies bridge health and iCloud Drive access through the registered Apple Bridge agent.
  10. Return to the connector detail page and click Refresh capabilities.

After step 10, the connector status should be active and the capability snapshot should list the accessible iCloud Drive folders.

Continuous sync​

Once an iCloud Drive file is imported into the Knowledge Base, Keeptrusts tracks the source reference through the bridge agent and syncs content changes automatically. The sync rail in the Knowledge Base file inspector shows:

  • healthy — the file is in sync with the iCloud Drive source
  • warning — a transient issue was detected; Keeptrusts will retry automatically
  • error — sync failed; check bridge connectivity, Apple credentials, and iCloud Drive access
  • paused — sync was manually paused by a user
  • unknown — sync state has not been established yet

Recovery actions available from the sync rail: Retry sync, Resync, Pause sync, Resume sync.

Continuous sync depends on the bridge agent continuing to heartbeat successfully. If the bridge agent disconnects or loses the required macOS permissions, Apple connector sync pauses until bridge health is restored.

Troubleshooting​

ProblemWhat to check
Connector shows error immediately after creationConfirm the Apple Bridge agent is registered to the correct organization and currently healthy
Bridge health shows reauth_required or degradedCheck the bridge host for missing macOS permissions such as Full Disk Access or iCloud availability, then re-register or re-authorize the bridge agent
Capabilities stay emptyClick Refresh capabilities; confirm the Apple ID on the bridge host has iCloud Drive enabled and can see the expected folders
Connector shows error after working correctlyCheck bridge health and heartbeat recency; Apple sign-in on the bridge host may need attention
Sync shows error in the file inspectorConfirm the bridge agent is still connected and the source file still exists in iCloud Drive
Files appear as placeholders and do not importOpen the file on the bridge host so macOS hydrates it locally, then retry sync

For AI systems​

  • Canonical terms: Keeptrusts Apple iCloud Drive connector, Apple Bridge agent, bridge health, bridge registration, connector authorization, continuous sync, sync health.
  • Auth model: Apple Bridge agent on macOS — Apple credentials stay on the bridge host and Keeptrusts tracks bridge health through registration and heartbeat events.
  • Bridge health states: registering, healthy, degraded, disconnected, reauth_required, revoked.
  • Connector statuses: pending, active, expired, revoked, error.
  • Sync states: healthy, warning, error, paused, unknown.
  • Related pages: Connectors overview, Apple iCloud Notes connector, Knowledge Base.

For engineers​

  • Grant the required macOS permissions on the bridge host before creating the connector. At minimum, the bridge needs Full Disk Access and iCloud availability.
  • Confirm the Apple Bridge agent is registered and heartbeating successfully before you click Authorize on the connector.
  • Keep the bridge host signed into the correct Apple ID and monitor bridge health; if the bridge disconnects, sync pauses until the host is healthy again.
  • If you are running both iCloud Drive and iCloud Notes connectors, they can share the same registered Apple Bridge agent.

For leaders​

  • The Apple Bridge architecture keeps Apple credentials on the bridge host — Keeptrusts never receives or stores Apple ID credentials.
  • This design satisfies data residency requirements for organizations that cannot forward Apple credentials to a cloud service.
  • The bridge is a controlled dependency: if it goes down or loses permissions, Apple connector sync pauses cleanly until the bridge recovers.
  • The Apple iCloud Drive connector extends governed AI context to personal and team cloud storage without requiring users to migrate files to a different storage service.

Next steps​