iCloud OAuth or a Signed-In Mac Connection

Apple gives third-party developers two distinct ways to reach Apple data, and they cover entirely different service sets. When developers search for an "iCloud OAuth" approach, they typically mean Apple's documented account-authorization channel for iCloud Mail, Calendar, and Contacts. That channel covers exactly those three services through open protocols. Every other Apple service — iMessage, Photos, Notes, Drive, Reminders, Safari, Find My, Home, Voice Memos, Shortcuts — has no published Apple authorization scope for third-party developers. For those services, a Mac signed in with the Apple Account is the access path.

Knowing which transport each service requires determines what your user completes during setup and which scopes your app can request.

What Apple's account authorization actually covers

Apple's support article Access your iCloud Mail, Calendar, and Contacts in third-party apps describes the user-facing step: when setting up a supported third-party app, the user enters their Apple Account email and selects Allow. The app then reaches the named service through its standard protocol. The user can revoke any app's access at any time from account.apple.com under Sign-In and Security → Account Data Sharing.

The three services and their protocols:

• Mail — IMAP for reading, SMTP for sending
• Calendar — CalDAV
• Contacts — CardDAV

Developers building a direct integration can apply through Apple's developer request form at developer.apple.com/contact/request/icloud-oauth2/. An Apple Developer account is required to access the form. Enrollment terms and approval apply. Figment is not an Apple-approved partner.

This channel handles none of Apple's native-app data stores. iMessage, Photos, Notes, Drive, and all other iCloud apps are outside its scope. Apple has not published authorization scopes for those services.

Why iMessage and most iCloud apps require a Mac

iMessage has no Apple-published REST API and no authorization scope for third-party developers. Messages.app stores conversations in a local SQLite database on the Mac and uses Apple's private push infrastructure to deliver them. BlueBubbles illustrates the architectural reality directly: its server reads from the Messages chat.db database and uses AppleScript for send operations — macOS is a hard requirement, with no Linux-container substitute.

The same constraint applies to Photos, Notes, Drive, Reminders, Safari sync, Voice Memos, Find My, Home, and Shortcuts. These services run through iCloud sync and native macOS frameworks. Apple has not published third-party authorization scopes for any of them. A Mac signed in with the Apple Account is the access path for each.

Service transport selection table

This table shows the transport architecture for each Apple service and Figment's current availability.

Calendar and Contacts: Apple's account-authorization path (CalDAV / CardDAV) is a direct third-party integration option that any qualifying developer can apply for. Figment's synthetic sandbox endpoints for Calendar and Contacts operate through the Mac connection, not through Apple's CalDAV/CardDAV channel.

Health: Mac account sign-in does not provide readable HealthKit data. Health data requires a separate supported-device integration or a user-initiated export.

How Figment maps to both transports

Figment issues grants through its hosted app-consent flow and executes native Apple operations on a signed-in isolated Mac. Your app never receives the Apple Account password. Native Apple sign-in and trusted-device approval happen as a separate step during connection setup on the Mac — not inside Figment's OAuth redirect.

Each service on a connection tracks its own status independently: connecting, needs_approval, syncing, ready, offline, reconnect_required, or revoked. A signed-in account does not mean every service is ready. Check GET /v1/connections/{connection_id} for per-service status before attempting reads or sends. The response includes connection.services.<service>.state for each granted service; services that are not ready reject operations.

A few details that affect scope planning:

• iMessage is the live product: messages:read covers history and search; messages:send is a separate scope and requires the user to select specific existing conversations during consent.
• Contacts, Calendar, and Reminders are available as synthetic read-only sandbox endpoints for development. Live customer access is not yet available.
• Read and write permissions are separate grants. Revoking one app grant stops only that app. Disconnecting the Apple connection stops every app grant and queued operation for that connection.
• iMessage history reflects what is on the connected Mac. Check historyComplete and hasMore rather than assuming full coverage; history can remain incomplete even when the connector is ready.

Connecting your app

Figment is the authorization issuer. Your app initiates the grant flow on Figment's hosted screen — not on an Apple authorization page. Figment issues the authorization code and tokens; Apple does not issue a Figment grant.

Your app receives a Figment access token scoped to the user's granted services. Tokens normally expire after 900 seconds; refresh using the supplied refresh token and store the rotated credential before making further API calls. The full PKCE flow and REST reference are in the OAuth for iCloud guide.

Pricing: $29/month per active live connection. Sandbox access is free and returns synthetic data. Access starts after setup completes — there is no immediate provisioning.

Connect Apple Account — register your app and open a free sandbox connection.

Related reading: OAuth for iCloud: Connect Apple Data to Your App · Figment vs BlueBubbles for iMessage Integration · Figment vs AirMessage for App Integrations · Figment vs Claw Messenger for iMessage Apps