# Let an Agent Use a Selected Saved Login

Canonical: https://figment.so/blog/icloud-keychain-agent-login

An AI agent can authenticate to a web service on your behalf using a credential you already saved in iCloud Keychain — without the agent or the developer app ever handling the password. The design centers on a **domain-bound action request**: the agent names exactly one destination, the system uses the matching credential, and the agent receives an **approval receipt** recording the outcome.

Figment does not currently offer a public credential API. The pattern below is an integration design. The Apple-native components it rests on are documented and real.

## How iCloud Keychain holds your credentials

iCloud Keychain syncs passwords, passkeys, and other account data across your Apple devices automatically. ([Apple Support](https://support.apple.com/en-us/120758)) On macOS, those credentials live in the data protection keychain — the same implementation that underpins iCloud Keychain on iOS and other Apple platforms. ([Apple Developer: TN3137](https://developer.apple.com/documentation/technotes/tn3137-on-mac-keychains))

Each process's access is limited to the access groups declared in its code-signing entitlements, so an app can only retrieve items in its own access groups. The data protection keychain is only available in a user login context; a background daemon cannot use it. macOS 11 and later synchronize all eligible keychain item classes across devices; earlier versions synchronized only the password classes. A credential belonging to Safari's access group is not readable by an arbitrary process, even one running in the same user session.

## The domain-bound request pattern

A well-designed agent credential flow asks for exactly the access it needs:

1. The agent submits a request naming **one domain** and **one action** (for example, `authenticate`).
2. A signed-in Mac worker executes the sign-in natively, using the saved credential for that domain.
3. The worker returns a receipt. The raw credential is never included.

The agent persists a stable **action key** before making the request. That key is unique to this specific action — reusing it for a different domain is an error. The key lets the agent reconcile an outcome after a network failure without triggering a duplicate sign-in.

```json
// Integration design — not a currently published Figment endpoint
{
  "domain": "example.com",
  "action": "authenticate",
  "actionKey": "auth-20261112-acme-001"
}
```

If no matching credential exists for the named domain, the request fails rather than prompting the user. Domain binding is the safety anchor: a confused or misdirected agent cannot silently redirect a sign-in to a different destination.

## The approval receipt

After the sign-in completes, the worker returns a structured receipt. No credential value appears in the payload.

```json
// Integration design — receipt shape; exact fields depend on implementation
{
  "actionKey": "auth-20261112-acme-001",
  "domain": "example.com",
  "state": "signed_in"
}
```

The receipt is the safe artifact. The agent can log it, pass it to downstream workflow steps, or store it as evidence of a completed action. Because it carries no credential, logging this receipt does not create a secrets exposure risk. Your application should still avoid logging the domain alongside any session tokens, verification codes, or message content produced by the authenticated session.

## What Apple natively enables

Apple provides two distinct credential flow patterns that an integration can build on:

**System-mediated sign-in.** `ASAuthorizationPasswordProvider` lets an app request a saved iCloud Keychain credential through system UI. The user selects and approves the credential; the authorization delegate may receive the username and password as an `ASPasswordCredential` after the user completes the system-mediated flow. ([Apple Developer: ASAuthorizationPasswordProvider](https://developer.apple.com/documentation/authenticationservices/asauthorizationpasswordprovider)) This is a scoped app-login flow with explicit system UI — not silent or bulk vault access.

**User-initiated credential exchange.** On iOS 26 / macOS 26 and later, `ASCredentialExportManager` lets a participating credential provider app transfer passwords and passkeys to another credential manager app through an out-of-process system UI. The operating system acts as intermediary; no credential data is written to the file system. ([Apple Developer: ASCredentialExportManager](https://developer.apple.com/documentation/authenticationservices/ascredentialexportmanager)) This requires the user to actively choose an importer app; it is not a background export.

Both flows require the requesting app to hold appropriate code-signing entitlements, to run in a user login context, and to surface a visible approval step. Neither bypasses macOS access group enforcement.

## Hard limits

Some things are outside any agent credential pattern:

- **Items marked *this device only*.** These do not sync to iCloud Keychain. A remote Mac worker cannot reach a credential that exists only on the user's local device. ([TN3137](https://developer.apple.com/documentation/technotes/tn3137-on-mac-keychains))
- **Items protected by biometrics.** Touch ID and Face ID requirements need in-person hardware approval. No remote flow satisfies this requirement.
- **Credentials for unapproved domains.** The user's approval list is the authorization boundary. An agent cannot request a sign-in for a domain the user has not explicitly approved.
- **Silent session renewal.** When a session expires, the agent must submit a new domain-bound request. It cannot silently reuse a stale session.
- **Bulk credential read.** This design grants access to one domain per approved request. It is not access to the full contents of the Keychain vault.

## Get started with Apple Connect

Figment does not currently offer a public credential API. When one is available, it will build on a connected, signed-in Mac and require explicit per-domain user approval before any action proceeds.

To explore what Figment offers today — including the iMessage REST API and synthetic sandbox access for Contacts, Calendar, and Reminders — [Connect Apple Account](/apple-connect/developers) to review available features and set up a developer connection.

---

*Related: [OAuth for iCloud: Connect Apple Data to Your App](/oauth-for-icloud) · [Use iCloud Keychain for Approved Account Actions](/icloud-keychain-api)*