# IPATool Authentication Methods: Store Authentication Protocol (SAP) and Keychain Storage

> Discover IPATool authentication methods including SAP and keychain storage. Learn how IPATool securely logs into the App Store with email, password, and 2FA.

- Repository: [Majd/ipatool](https://github.com/majd/ipatool)
- Tags: internals
- Published: 2026-09-04

---

**IPATool authenticates with Apple's App Store using the Store Authentication Protocol (SAP), supporting email and password login with optional two-factor authentication (2FA), persisting credentials in the macOS keychain, and providing explicit revocation commands.**

The `majd/ipatool` command-line interface implements a secure authentication workflow for accessing iOS app packages from the App Store. Understanding the authentication methods provided by IPATool requires examining how the tool leverages Apple's proprietary Store Authentication Protocol alongside native macOS security features. The implementation spans multiple packages including core appstore logic, SAP cryptographic signing, and system keychain integration.

## Store Authentication Protocol (SAP) Login Flow

The primary authentication method uses SAP to communicate with Apple's authentication endpoint at `/WebObjects/MZFinance.woa/wa/authenticate`. Located in [`pkg/appstore/appstore_login.go`](https://github.com/majd/ipatool/blob/main/pkg/appstore/appstore_login.go), the `Login` function orchestrates a multi-step cryptographic handshake that establishes a trusted session with Apple's servers.

### Machine Identity and Configuration Bag

Before transmitting credentials, IPATool establishes a **machine identity** using the device MAC address to generate a GUID and machine ID. The [`pkg/appstore/appstore_bag.go`](https://github.com/majd/ipatool/blob/main/pkg/appstore/appstore_bag.go) file implements bag retrieval, fetching SAP configuration from Apple's servers to obtain the `AuthEndpoint` and other protocol parameters required for the authentication sequence.

### Cryptographic Request Signing

The [`internal/sap/signer.go`](https://github.com/majd/ipatool/blob/main/internal/sap/signer.go) file implements the SAP action signer, which cryptographically signs login requests according to Apple's protocol requirements. This signing process ensures the authentication payload meets Apple's security standards before transmission to the App Store servers.

### Authentication Transmission and Retry Logic

The `sendAuthenticationRequest` function in [`pkg/appstore/appstore_login.go`](https://github.com/majd/ipatool/blob/main/pkg/appstore/appstore_login.go) handles the actual HTTP transmission, implementing retry logic for transient HTTP errors (204 and 5xx status codes) and following pod redirects automatically. When Apple redirects to a different authentication pod, `parseLoginResponse` validates that the redirect URL points to the expected authentication path (`/WebObjects/MZFinance.woa/wa/authenticate`) before retrying the login request with the new pod URL.

## Two-Factor Authentication (2FA) Handling

When Apple requires additional verification, the login flow returns `ErrAuthCodeRequired`. Users must then retry the login with the `AuthCode` field populated. The [`cmd/auth.go`](https://github.com/majd/ipatool/blob/main/cmd/auth.go) file contains `loginCmd`, which orchestrates interactive prompting for 2FA codes when the initial authentication attempt indicates multi-factor authentication is required.

The following example demonstrates the interactive login flow:

```go
// CLI command: `ipatool auth login -e user@example.com -p secret`
output, err := dependencies.AppStore.Login(appstore.LoginInput{
    Email:    "user@example.com",
    Password: "secret",
    AuthCode: "", // Omitted - will be requested if Apple asks for 2FA
})
if err != nil {
    // Handle errors such as appstore.ErrAuthCodeRequired
}
fmt.Printf("Logged in as %s (%s)\n", output.Account.Name, output.Account.Email)

```

When 2FA is required, provide the code on the second attempt:

```go
// First attempt fails with ErrAuthCodeRequired → retry with auth code
output, err := dependencies.AppStore.Login(appstore.LoginInput{
    Email:    "user@example.com",
    Password: "secret",
    AuthCode: "123456", // 2FA code from Apple
})

```

## Credential Storage in macOS Keychain

After successful authentication, IPATool persists account data using the **macOS keychain**. The `Account` struct—containing the user's name, email, password-token, directory-services ID, storefront, and pod information—is marshalled to JSON and stored under the service name `ipatool-auth.service`.

The [`pkg/keychain/keychain.go`](https://github.com/majd/ipatool/blob/main/pkg/keychain/keychain.go) file provides the generic wrapper for these operations, while [`pkg/appstore/appstore_account_info.go`](https://github.com/majd/ipatool/blob/main/pkg/appstore/appstore_account_info.go) implements the `AccountInfo` method for retrieving stored credentials. Subsequent CLI commands access this stored data without requiring re-entry of the Apple ID password.

Retrieve stored account information using:

```go
info, err := dependencies.AppStore.AccountInfo()
if err != nil {
    // No stored credentials or keychain error
}
fmt.Printf("Current account: %s (%s)\n", info.Account.Name, info.Account.Email)

```

## Revoking Authentication

To terminate an authenticated session, IPATool provides the revocation method implemented in [`pkg/appstore/appstore_revoke.go`](https://github.com/majd/ipatool/blob/main/pkg/appstore/appstore_revoke.go). The `Revoke` function deletes the stored "account" entry from the keychain, effectively logging the user out. This is exposed through the `revokeCmd` in [`cmd/auth.go`](https://github.com/majd/ipatool/blob/main/cmd/auth.go).

Execute revocation using:

```go
if err := dependencies.AppStore.Revoke(); err != nil {
    // Handle revocation error
}
fmt.Println("Credentials revoked – you are now logged out")

```

## Summary

- **Store Authentication Protocol (SAP)** provides the cryptographic foundation for IPATool's authentication with Apple's `/WebObjects/MZFinance.woa/wa/authenticate` endpoint.
- **Three core operations** comprise the authentication interface: `Login` (with optional 2FA), `AccountInfo` (keychain retrieval), and `Revoke` (credential deletion).
- **Machine identity** is derived from the device MAC address to generate GUIDs and authentication tokens as implemented in [`pkg/appstore/appstore_login.go`](https://github.com/majd/ipatool/blob/main/pkg/appstore/appstore_login.go).
- **macOS keychain** securely persists JSON-encoded account data under the service name `ipatool-auth.service`, eliminating the need for repeated password entry.
- **Pod redirect handling** and transient error retry logic ensure robust authentication across Apple's distributed infrastructure.

## Frequently Asked Questions

### How does IPATool handle two-factor authentication?

IPATool detects 2FA requirements through the `ErrAuthCodeRequired` error returned by `parseLoginResponse` in [`pkg/appstore/appstore_login.go`](https://github.com/majd/ipatool/blob/main/pkg/appstore/appstore_login.go). When this error occurs, the CLI prompts for a 2FA code and retries the authentication request with the `AuthCode` field populated in the `LoginInput` struct.

### Where does IPATool store my Apple ID credentials?

IPATool stores credentials in the **macOS keychain** under the service name `ipatool-auth.service`. The implementation in [`pkg/keychain/keychain.go`](https://github.com/majd/ipatool/blob/main/pkg/keychain/keychain.go) handles the secure storage of JSON-encoded account data including authentication tokens, eliminating the need to store plaintext passwords in configuration files.

### What protocol does IPATool use to authenticate with Apple?

IPATool uses Apple's proprietary **Store Authentication Protocol (SAP)**. The implementation involves cryptographic request signing via [`internal/sap/signer.go`](https://github.com/majd/ipatool/blob/main/internal/sap/signer.go) and configuration retrieval through the bag endpoint as defined in [`pkg/appstore/appstore_bag.go`](https://github.com/majd/ipatool/blob/main/pkg/appstore/appstore_bag.go).

### How do I completely log out of IPATool?

Execute the `ipatool auth revoke` command, which calls the `Revoke` function in [`pkg/appstore/appstore_revoke.go`](https://github.com/majd/ipatool/blob/main/pkg/appstore/appstore_revoke.go). This removes the account entry from the macOS keychain, invalidating the stored authentication tokens and requiring fresh credentials on the next login attempt.