# Diagnose an Unavailable Apple Data Connector

Canonical: https://figment.so/blog/icloud-service-unavailable

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:

```bash
curl -s -X GET https://figment.so/api/apple-connect/v1/connections/con_... \
  -H "Authorization: Bearer ACCESS_TOKEN"
```

The response has this shape:

```json
{
  "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](/apple-connect/account).

## 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](/blog/mac-connector-permissions) 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](https://account.apple.com) under Sign-In and Security → Account Data Sharing ([Apple Support HT121539](https://support.apple.com/en-us/121539)); the full Figment connection grant is managed from your [connection account screen](/apple-connect/account). 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](/apple-connect/developers).

## 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](https://support.apple.com/en-us/102545)). 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](/blog/imessage-history-not-syncing).

## 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](https://www.apple.com/support/systemstatus/) 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](/apple-connect/developers). To review or update an existing connection's granted services, visit your [connection account screen](/apple-connect/account).

**Related reading**
- [OAuth for iCloud: Connect Apple Data to Your App](/oauth-for-icloud)
- [Grant the Mac Permissions Your Connector Needs](/blog/mac-connector-permissions)
- [Fix Missing iMessage History on a Connected Mac](/blog/imessage-history-not-syncing)
- [Prevent Duplicate iMessages After a Timeout](/blog/prevent-duplicate-imessages)