Authentication

xcross signs and provisions in-process, for Flutter and Compose alike. Pick one method.

xcross auth --apple-id you@example.com
# prompts for password + 2FA code

xcross auth --issuer-id <uuid> --key-id <id> --private-key ./AuthKey_ABC123.p8

Which one?#

How the session is chosen#

Saving an API key clears any Apple ID session. xcross auth clean removes everything: the key, the Apple ID session and every certificate, private key and profile xcross minted. The downloaded ADI libraries stay. (auth clear was renamed in 2.0.)

Working offline#

Apple is only needed to provision: the first run of an app on a device, or when something about it changes. After that, flutter run and compose run keep working without a network.

XCROSS_OFFLINE=1 xcross flutter run   # skip Apple entirely, even when online

Offline signing still needs, for that app and device:

• one earlier online run, so a profile is cached
• a profile that lists the device and hasn’t expired (7 days on free accounts)
• no new extension, capability or App Group since then

If one is missing, xcross says which and asks you to reconnect once. A dead network can’t stall the run: the Apple ID access check gives up after 20 seconds.

App ID#

On an app’s first device build, xcross asks whether to register the original bundle id or an XCR- prefixed one and saves it as bundle_id in pubspec.yaml (or xcross_project.yaml). Pick original for Sign in with Apple, push, passkeys and associated domains. See CLI reference.

Remote Anisette#

Apple’s GrandSlam login expects Mac-matching machine attestation (anisette). By default xcross auth uses a remote Omnisette v3 server (https://mac-ani.jkcoxson.com) that synthesizes those headers.

xcross auth --apple-id you@example.com
# uses https://mac-ani.jkcoxson.com

xcross auth --apple-id you@example.com \
  --anisette-url https://example.test
# or: XCROSS_ANISETTE_URL=https://example.test

Self-host omnisette-server if you don’t want a public relay. The chosen URL is stored with the session so later signing hits the same backend (override with XCROSS_ANISETTE_URL).

Public servers#

Mac Omnisette servers from SideStore’s public directory — these work with --anisette-url (and as alternatives to the default).

ADI libraries#

--adi-library-dir is a legacy opt-in to local Android ADI libraries (libCoreADI.so, libstoreservicescore.so). Apple currently rejects that identity (-80046); prefer the Omnisette default above. On Windows / Linux (x64 or ARM64) the matching slice still downloads automatically when you force this path.