# Give an Agent Access to Selected iCloud Files Canonical: https://figment.so/blog/icloud-drive-agent-files The direct answer: you give an agent access to selected iCloud Drive files by connecting through Figment, which routes operations through a signed-in Mac and enforces folder-level grants so the agent only reaches paths the user deliberately chose to share. This article explains the folder grant model, the cloud-placeholder file states that determine whether a file is immediately readable, and the authorization flow your app needs to complete. iCloud Drive file listing and reading endpoints are integration design pending published API contracts. The Apple sync model and Figment authorization flow are both described accurately below. ## What "selected files" means in iCloud Drive iCloud Drive is not a flat file server. It is a sync layer that runs on a Mac. Figment routes all Drive operations through a signed-in isolated Mac, so the only files an agent can reach at request time are files that have already synced to that Mac. "Selected" refers to the folders a user approves during account connection. That selection is enforced at the grant level: the agent's access token covers those paths and nothing else. If a user wants to expose their `Projects/` folder but not their personal photos archive, they grant one and withhold the other. The Desktop and Documents folders are opt-in at the Apple Account level — they sync to iCloud Drive only when the user has enabled [Desktop and Documents in iCloud Drive settings](https://support.apple.com/en-us/109344) — and separately opt-in at the grant level. This scoping limits blast radius if an agent misbehaves and matches how most users think about sharing: they want to give an agent a working folder, not an entire drive. ## Cloud-placeholder download states This is the detail that surprises most developers. Apple's Optimize Mac Storage feature can remove local copies of files to free disk space. The file still appears in Finder as a lightweight placeholder. The actual bytes live in iCloud until something requests a download. A file in placeholder state is not readable by an agent. The Mac must download it first. Apple's Mac Help [documents the iCloud Drive status values](https://support.apple.com/guide/mac-help/check-icloud-drive-file-folder-status-mac-mchlc994344b/mac) visible in Finder's iCloud Status column. Each has a different implication for agent access: | Finder status | What it means | Agent can read? | What to do | |---|---|---|---| | **In iCloud** | Placeholder only; bytes are in iCloud, not on the Mac | No | Return a "not yet available" response; retry after the Mac downloads the file | | **Downloaded** | Local copy is current; available with or without internet | Yes | Proceed normally | | **Keep Downloaded** | Pinned locally; Mac will not evict this file | Yes | Proceed normally | | **Waiting to Upload** | New or modified file on Mac; not yet synced to iCloud | Yes (local copy exists) | Readable, but a second device may see an older version until upload completes | | **Ineligible** | Item exceeds the 50 GB limit for an individual file or folder, or the item type cannot be stored in iCloud | No | The file cannot live in iCloud Drive; ask the user to move it out of the granted folder | | **Out of Space** | iCloud storage quota is full | Possibly (local copy may still exist) | User must free iCloud storage before reliable sync resumes | Build your agent to treat an **In iCloud** response as temporary unavailability, not a permanent error. Inform the caller that the file is queued for download and retry after a short interval — do not silently skip the file or report it as missing. ## How folder grants scope the connection When a user connects their Apple Account through Figment, they select which Drive folders to expose. Each selection becomes a named grant tied to the connection. Your app's access token covers those grants and nothing else — no other folder in iCloud Drive, no other iCloud service, and no other Apple account. Revoking your app's grant stops access to those folders immediately without affecting other apps or services on the same Apple Account. If the user disconnects the Apple Account entirely, every grant and every queued operation tied to that connection stops. Audit records for Drive operations should omit file contents and personal metadata beyond what is needed to identify the operation. ## Authorization and connection setup Register your app at [/apple-connect/developers](/apple-connect/developers). Figment uses PKCE-protected OAuth. Generate a code verifier, derive the S256 challenge, and validate the `state` parameter on redirect to protect against CSRF. ``` GET https://figment.so/apple-connect/authorize ?client_id=YOUR_CLIENT_ID &redirect_uri=https://yourapp.example/callback &response_type=code &scope=REQUESTED_SCOPES &state=CSRF_TOKEN &code_challenge=YOUR_CODE_CHALLENGE &code_challenge_method=S256 ``` After the user approves, exchange the code for tokens: ``` POST https://figment.so/api/apple-connect/oauth/token Content-Type: application/x-www-form-urlencoded grant_type=authorization_code &client_id=YOUR_CLIENT_ID &redirect_uri=https://yourapp.example/callback &code=RETURNED_CODE &code_verifier=YOUR_VERIFIER ``` The response includes `access_token`, `refresh_token`, `expires_in` (900 seconds), `scope`, and `connection_id`. Store the `connection_id`; it anchors every subsequent request. Access tokens expire after 900 seconds — refresh before they expire using `grant_type=refresh_token`, and always store the rotated refresh token returned in the response. Requested scopes and their exact string values are assigned during app registration in the developer dashboard. Use the values shown there. Check connection status before attempting any file operation: ``` GET https://figment.so/api/apple-connect/v1/connections/{connection_id} Authorization: Bearer ACCESS_TOKEN ``` The response has the shape `{connection:{id, mode, services, ...}}`. Each entry in `services` is an object with `state`, `reason`, and `observedAt` (epoch milliseconds). Service states include `connecting`, `needs_approval`, `syncing`, `ready`, `offline`, `reconnect_required`, and `revoked`. Only granted services appear in the `services` map. A `needs_approval` state means the user must complete a step on their trusted device — that is an Apple account requirement, not a Figment one. A `ready` state does not guarantee complete history or successful delivery for any service. Non-ready services reject operations. The connection endpoint is authorized and can reject a non-ready or revoked connection with a non-2xx response. Handle that path. For connection setup and troubleshooting, use [/apple-connect/account](/apple-connect/account). ## What an agent can access: integration design This section describes the intended design based on confirmed Apple sync behavior. Drive-specific file listing and file-reading endpoints are not yet part of the published API surface. Developers should treat the following as the design target, not an executable interface. A ready Drive connector is designed to give your agent access to: - **Synced files and folders** within granted paths - **Desktop and Documents** contents, if the user opted those folders into iCloud Drive and included them in their grant - **File metadata**: name, path, size, modification date, and download status - **File contents**: for files whose iCloud status is Downloaded or Keep Downloaded The agent cannot access files on an iPhone or iPad filesystem directly — only what has synced to the connected Mac. Files in `In iCloud` state must be downloaded to the Mac before an agent can read them. ## Drive scope limits to design around **Files or folders larger than 50 GB** are ineligible for iCloud Drive. Apple's Mac Help confirms this limit. Such items receive an Ineligible status and will not appear in Drive listings. **Items in cloud-only state** can fill most of a granted folder if Optimize Mac Storage has been active for a while. Design your agent to work through the files that are locally available, surface the cloud-only items as pending, and check back after download rather than treating them as absent. **Desktop and Documents** are opt-in at the Apple Account level and again at the grant level. Do not assume they are included in a Drive grant unless the user explicitly selected them. **Write permissions** are separate from read. A read-only scope does not grant the ability to modify or delete files. --- Ready to start? [Register your app](/apple-connect/developers) to get a client ID and test with the free sandbox. Live connections are $29/month each; sandbox access is free. For a broader look at Apple data connectors — including Notes, Photos, and Safari — see [Connect Apple Notes, Photos, Files, and Safari](/apple-data-connectors). To understand the authorization model in depth, see [OAuth for iCloud: Connect Apple Data to Your App](/oauth-for-icloud). For agents that trigger actions rather than read files, [Create Apple Reminders with EventKit on Mac](/blog/apple-reminders-eventkit) covers the write side of native Mac integrations.