Diagnose an Unavailable Apple Data Connector
When an iCloud connector goes quiet or returns an error, the fastest path forward is reading the exact state Figment reports for each service — not disconnecting and reconnecting, not re-authorizing blindly. Every connector service carries a machine-readable state field. Match the state to its cause, then take the one action that actually resolves it.
Check the connector state first
Fetch the connection record before attempting any fix:
curl -s -X GET https://figment.so/api/apple-connect/v1/connections/con_... \
-H "Authorization: Bearer ACCESS_TOKEN"
The response has this shape:
{
"connection": {
"id": "con_...",
"mode": "live",
"services": {
"messages": {
"state": "needs_approval",
"reason": "trusted_device_required",
"observedAt": 1767280440000
}
}
}
}
Only services included in the original grant appear under services. Each entry carries state, reason, and observedAt (epoch milliseconds). The reason field narrows the cause when a state has more than one trigger. If the endpoint returns a non-2xx status, the connection may be revoked, the access token may have expired, or the service may be in a non-serviceable state the endpoint declines to serve — refresh the token first, then re-fetch; if the problem persists, check the connection's current status at your connection account screen.
Service state reference
This matrix covers every state a connector service can report. Use the Fix column to decide what to do next — do not skip to a fix without confirming the state.
| State | What it means | Typical cause | Fix |
|---|---|---|---|
connecting | Handshake in progress | Normal during first setup | Wait up to a few minutes; re-fetch |
needs_approval | User action required | Trusted-device step, Mac system permission, or app consent not yet completed | Open the Figment connection screen to complete the pending step |
syncing | Authorized; loading history | First-time sync or large history backfill | Wait; check historyComplete in list responses before reading |
ready | Fully operational | — | Proceed with API calls; ready does not guarantee complete history |
offline | Mac worker cannot reach iCloud | Mac sleeping, network down, or iCloud signed out on the Mac | Restore Mac connectivity and iCloud sign-in; no user re-auth needed |
reconnect_required | Apple session expired or invalidated | Apple ID password change, security event, or long inactivity | User must re-authenticate through the connection screen |
revoked | Grant explicitly removed | User or Apple revoked third-party access | User must reconnect through the full setup flow |
The ready state confirms Figment can submit operations. It does not confirm that message history is complete. Always check historyComplete and hasMore in list responses rather than assuming full coverage.
Clear a needs_approval state
A needs_approval state has three distinct triggers. The reason field tells you which one applies.
Trusted-device step not completed. Apple requires a trusted device to approve iCloud sign-in on a new Mac. This step is separate from Figment's app-consent flow. The user must approve the sign-in notification on their iPhone, iPad, or another trusted Apple device before the connector can advance. Opening the Figment connection screen surfaces the pending prompt.
Mac system permission not yet granted. On macOS, contacts, calendars, and other data types each require an explicit toggle under System Settings → Privacy & Security. Flipping the iCloud switch alone does not grant application-level access to those types. See Grant the Mac Permissions Your Connector Needs for the full list of required toggles.
App consent not completed. The Figment connection screen may have been closed before every consent step was finished. Re-open it and step through each approval prompt in sequence. Each capability can require a separate approval.
Handle offline, reconnect_required, and revoked
These three states all block operations, but they need different remediation.
offline means the Mac worker cannot reach iCloud. The Mac may be asleep, on a network that blocks iCloud, or signed out of the Apple Account. No user re-authentication is required: once the Mac is reachable and iCloud is signed in, the connector should recover without further action.
reconnect_required means Apple invalidated the session. This happens after an Apple ID password change, a security event such as a two-factor authentication method reset, or an extended period without activity. The reason field usually identifies the trigger. The user must open the connection screen and authenticate again to restore the Apple session before the connector can process operations.
revoked means the grant was explicitly removed. Revoking an app's grant stops operations on that grant; if the entire Apple connection is disconnected, every queued operation across the connection is cancelled. Apple documents that users can withdraw third-party authorization for Mail, Calendar, and Contacts from account.apple.com under Sign-In and Security → Account Data Sharing (Apple Support HT121539); the full Figment connection grant is managed from your connection account screen. Once in a revoked state, the grant cannot be restored silently — the user must go through the full connection and consent flow again from the Apple Connect setup page.
Per-service gaps inside a ready connector
A connector can be ready for one service and needs_approval or offline for another. Always check the state for the specific service you are calling, not just the top-level connection record.
A common gap: iMessage shows ready while SMS, MMS, and RCS forwarding stays unavailable. These message types require an eligible iPhone signed in to iCloud with the same Apple Account, powered on, and online. When Messages in iCloud is enabled on the iPhone, forwarding for SMS, MMS, and RCS is built in — a separate Text Message Forwarding toggle is not always required (Apple Support HT102545). That is an iPhone-side configuration; no change on the Figment side will enable it without those prerequisites in place.
Scope gaps are equally common. messages:read covers both message history and search, but messages:send is a separate scope. A connector can be authorized for reads and not for sends. Confirm the grant's scope matches what your code requests — a send attempt on a connection that holds only messages:read will be rejected.
For incomplete message history on an otherwise ready connector, see Fix Missing iMessage History on a Connected Mac.
If Apple's own services are degraded
A connector can be healthy on the Figment side while Apple's underlying iCloud infrastructure has an incident. If multiple connectors go offline simultaneously, check Apple's System Status page before investigating individual connections. Apple lists iCloud Drive, iCloud Mail, iMessage, and other services individually. When Apple reports an active incident, the connector should recover automatically once Apple resolves it — no action on the Figment side is needed.
To reconnect after a revoked or reconnect_required state, start the reconnection flow from the Apple Connect setup page. To review or update an existing connection's granted services, visit your connection account screen.
Related reading
