OAuth for iCloud: Connect Apple Data to Your App
Short answer: Figment Apple Connect gives your app a scoped, Figment-issued OAuth grant tied to a user's existing Apple connection. Your app redirects the user to a Figment-hosted consent screen; your codebase never receives the Apple Account password.
Connection setup and app authorization are two separate events
This distinction resolves most confusion when a user cannot complete the grant flow:
| Scenario | What must happen first | Your app's action |
|---|---|---|
| Sandbox: no connection yet | None — synthetic sandbox connections require no Apple sign-in | Use a sandbox connection_id from developer setup |
| Live: user has no Figment connection | User completes Apple connection setup on a connected Mac (native Apple sign-in and trusted-device approval happen during this step, not during your OAuth redirect) | Direct user to connection setup before starting OAuth |
| Connection exists; no grant for your app | — | Redirect to /apple-connect/authorize |
| Grant exists; access token expired | — | POST to /api/apple-connect/oauth/token with grant_type=refresh_token |
Connection setup is the user's Apple Account connection through Figment — native Apple sign-in and trusted-device two-factor authentication happen here, on a connected Mac. This step is entirely separate from the OAuth redirect your app initiates. The Figment OAuth redirect does not itself perform Apple authentication.
App authorization is the Figment OAuth flow. The user signs into Figment, selects their existing Apple connection, and approves each scope individually. Figment redirects back to your registered callback with a Figment-issued authorization code. Figment is the token issuer. Apple does not issue this grant or these tokens.
One more distinction worth naming: Apple natively supports third-party authorization for iCloud Mail, Calendar, and Contacts — users can grant a compatible app access directly from Apple (Apple HT121539). That is Apple's own authorization path, not a Figment feature. Figment's consent model is a separate system: it extends user-approved, scoped app access to Apple services using an authorized Mac session held on the user's behalf. "Sign in with Apple" is a third distinct mechanism that proves identity only — it is not data-access authorization.
Registering your app
Register at figment.so/apple-connect/developers to receive a client_id and configure your callback URL. The callback URL is developer-defined — you register your own exact HTTPS path during setup.
Figment Apple Connect uses an authorization-code flow with PKCE (S256). Generate a fresh state value and a fresh PKCE verifier for every authorization attempt, validate the returned state before exchanging the code, and exchange it at POST /api/apple-connect/oauth/token. The token response includes access_token, refresh_token, expires_in, scope, and connection_id. Tokens are opaque. Access tokens normally expire after 900 seconds; store the new refresh token after each refresh and serialize refresh per grant. Full PKCE request shapes are in the developer setup docs at figment.so/apple-connect/developers.
Check service status before you read or write
A signed-in Apple Account does not mean every service is ready. Each service has its own independent status; possible values include connecting, needs_approval, syncing, ready, offline, reconnect_required, and revoked. Not every service passes through every state, and a service can become offline or revoked at any point.
A non-ready or revoked service rejects operations with a non-2xx response — handle those rather than assuming success. For setup status, use the account connection screen at figment.so/apple-connect/account. You can inspect the connection state directly when needed:
GET https://figment.so/api/apple-connect/v1/connections/con_...
Authorization: Bearer ACCESS_TOKEN
Response: {connection:{id,mode,services,...}}. Each service entry carries state, reason, and observedAt. A ready state on one service says nothing about another, and ready does not prove complete message history — treat each service independently.
Service permissions
The same connect-then-grant model applies across services. iMessage is the reference example in this section.
| Service | Scope | Notes |
|---|---|---|
| iMessage history and search | messages:read | One scope covers both — no separate search permission |
| iMessage send | messages:send | Requires selected existing conversations in the send grant |
For reads, check historyComplete and hasMore — history may be incomplete while the connector catches up. SMS, MMS, and RCS need an eligible connected iPhone; Messages in iCloud includes their forwarding when enabled, with a separate Text Message Forwarding switch as an alternative.
For sends, generate and persist one idempotency key per intended action before its first request. A failed receipt polled again returns the same failure — it does not retry the send. An unknown receipt status means poll the original key; never issue a new key to resend.
Endpoint details for history, search, send, and receipts are in the developer setup docs at figment.so/apple-connect/developers.
Pricing
Sandbox is free and includes synthetic data; it cannot send to real people. Live connections are $29 per active connection per month. The initial checkout covers one live connection. Access starts after setup.
Revocation and account management
Revoking a single app grant stops that app's access and queued operations without affecting other apps on the same Apple connection. Disconnecting the Apple Account stops every grant and every queued operation for that connection. As a design practice, your app's own audit records should omit Apple Account passwords, two-factor verification codes, and message bodies from application logs.
Manage grants at figment.so/apple-connect/account. For Apple's native Mail, Calendar, and Contacts authorization, users manage per-app access at account.apple.com under Sign-In and Security › Account Data Sharing (Apple HT121539).
Get started
Register your app and begin building in sandbox at figment.so/apple-connect/developers.
