# Reconnect an Apple Account Without Losing App Grants

Canonical: https://figment.so/blog/reconnect-apple-account

When Figment reports `reconnect_required` for an Apple Account connection, your app grants are paused—not revoked. The underlying grant records survive the interruption. Reads and writes stop returning data until the session is restored, but once the user completes reconnect on the Figment account screen, Figment is designed to run a scope recheck and restore your grants. No new OAuth authorization flow is required from your app's side.

## What puts a connection into reconnect_required

A Figment connection runs on a signed-in Mac host tied to a specific Apple Account. Several conditions can interrupt that session without permanently removing app access:

- **Session expiry.** Apple requires periodic re-authentication on the Mac. The cadence is not published, but long-idle hosts eventually need a fresh sign-in.
- **Trusted-device gap.** When a Mac is newly enrolled or re-enrolled, iCloud Keychain sync requires approval from another trusted device or via an existing device passcode ([Apple Support](https://support.apple.com/en-us/120758)). If that approval does not arrive, the connection stalls.
- **Apple Account password change.** Changing the account password invalidates the session on the Mac host.
- **iCloud signed out on the Mac.** All devices must be signed in to iCloud with the same Apple Account—a sign-out or credential mismatch requires the user to sign back in with the correct account ([Apple Support](https://support.apple.com/en-us/102545)).

None of these events by themselves revoke your app's grant. They interrupt the connection until the account owner re-authenticates.

## The reauth lifecycle: paused jobs and scope rechecks

**Integration design:** The lifecycle below shows how the reconnect feature is designed to work. Verify queue-retention and scope-recheck behavior with Figment before writing production recovery logic.

This is what distinguishes a session lapse from a true revocation. When a connection enters `reconnect_required`, Figment does not tear down the grant — it pauses it. Queued operations are designed to be held, not discarded. Once the user completes reauth with a fresh Apple sign-in, Figment runs a per-service scope recheck before resuming anything.

```
  reconnect_required
  │
  ├─ App grants           → paused (grant record intact)
  ├─ Queued operations    → held (not discarded)
  └─ Read / write calls   → rejected (services not ready)

  User opens /apple-connect/account:
  fresh Apple sign-in + trusted-device confirmation
  │
  └─ Status transitions: reconnect_required → connecting → syncing
           │
           └─ Scope recheck runs per service
                ├─ Previously ready     → syncing → ready (grants resume)
                ├─ needs_approval       → returns to needs_approval
                └─ Explicitly revoked   → stopped (see table below)
```

The scope recheck runs server-side after the user completes Apple sign-in. Your app does not trigger it and does not need to re-request authorization. The recheck reads the current permission state for each service on the connection — the account owner is not asked to re-approve your app's scope, because that grant is recorded separately from the connection session.

## How to reconnect in five steps

**Step 1 — Detect the state.**
Poll `GET https://figment.so/api/apple-connect/v1/connections/{connection_id}` with your Figment access token. A successful response returns a `connection` object whose `services` property is an object keyed by service name. Each service entry has `state`, `reason`, and `observedAt` (epoch milliseconds). Only granted services appear. For example, `connection.services.messages.state` tells you the state of the iMessage service.

The endpoint enforces authorization and readiness; handle non-2xx responses — a revoked or expired connection may be rejected rather than returning a diagnostic object. For current setup and reconnect status, use the [account screen](/apple-connect/account).

When a service you depend on shows `state: "reconnect_required"`, reauthentication is needed before operations on it can resume.

Do not attempt reads or sends in this state. Non-ready services reject operations, and retrying under a new idempotency key when you have an unresolved `unknown` outcome creates duplicate-action risk. See [Prevent Duplicate iMessages After a Timeout](/blog/prevent-duplicate-imessages) for guidance on unknown receipts.

**Step 2 — Notify the account owner.**
Surface a prompt in your UI that asks the user to reconnect their Apple Account. The reconnect action happens on the Figment-hosted screen; your app does not handle or receive the Apple password.

**Step 3 — Send the user to `/apple-connect/account`.**
The account screen lists all active and interrupted connections. The user selects the interrupted connection, initiates reconnect, and completes a fresh Apple Account sign-in and trusted-device confirmation. This must be the same Apple Account that owns the connection — not a new account.

**Step 4 — Wait for `ready` on the services you use.**
Poll the same connection endpoint at a reasonable interval. The `services` object in the response carries a per-service state. Wait until the specific service you need reports `state: "ready"` before resuming operations — a connection is not fully available just because the account is signed in again.

**Step 5 — Resume without re-authorizing.**
Your existing Figment access token still identifies your app. The scope recheck runs server-side. When a service returns to `ready`, reads and writes on that service resume automatically under your existing grant.

## What the scope recheck can change

A scope recheck reads current permission state; it does not undo your app's grant. However, two situations can produce a different post-reconnect result than the pre-disconnect state:

**Mac-level permissions.** If a Mac permission was revoked on the host while the connection was down — Full Disk Access removed or Automation permission to Messages disabled — the affected service returns to `needs_approval` after the recheck rather than `ready`. See [Grant the Mac Permissions Your Connector Needs](/blog/mac-connector-permissions) for the approval steps.

**Incomplete history.** Native source history may be incomplete for a period after a service returns to `ready`. Check the `historyComplete` field in message and chat responses rather than assuming full coverage. The [Fix Missing iMessage History on a Connected Mac](/blog/imessage-history-not-syncing) guide walks through that recovery path.

## reconnect_required versus revoked

These two statuses look similar from the outside — operations stop in both cases — but they have different recovery paths.

| Status | App grants | Queued operations | Recovery |
|---|---|---|---|
| `reconnect_required` | Paused | Held | User re-auths on account screen; grants resume after scope recheck |
| `revoked` | Stopped | Stopped | User must reconnect and re-grant app access |

A `revoked` status is created when the user explicitly disconnects. Once an app's access is removed, it cannot access data again until the user re-authorizes ([Apple Support](https://support.apple.com/en-us/121539)). That citation covers Apple's authorization model for Mail, Calendar, and Contacts; in Figment terms, the same principle applies — a new Figment authorization flow is required before operations can resume.

One important scope distinction: revoking one app's grant stops that app only. Fully disconnecting the Apple Account connection stops every app grant and every queued operation tied to that connection. If multiple apps share one connection, a full disconnect affects all of them simultaneously.

## Get your connection back

If a connection in your account is currently reporting `reconnect_required`, go to [/apple-connect/account](/apple-connect/account) and complete the reconnect. The grant resumes after the scope recheck without any change to your integration code.

If you are setting up Figment for the first time, start at the [developer registration page](/apple-connect/developers). Each live Apple connection is $29/month; sandbox access is free and lets you work through the reconnect flow with synthetic data before going live.

---

**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)