macOS runner: notarytool "HTTP status code: 401 ... Unable to authenticate" in CI

notarytool reached the Apple notary service but the credentials were rejected with a 401. Either the App Store Connect API key, issuer, and key ID are wrong, or the Apple ID and app-specific password do not match.

What this error means

A xcrun notarytool submit step fails with "Error: HTTP status code: 401. Unable to authenticate." or "Invalid credentials. Username or password is incorrect."

Error: HTTP status code: 401. Unable to authenticate.
Invalid credentials. Username or password is incorrect.

Common causes

Wrong or missing App Store Connect API key

The key ID, issuer ID, or .p8 key file passed to notarytool does not match a valid App Store Connect key, so authentication is refused.

A regular password instead of an app-specific one

When authenticating by Apple ID, notarytool requires an app-specific password, not the account password; the regular password yields a 401.

How to fix it

Authenticate with an API key

1. Create an App Store Connect API key and store the .p8, key ID, and issuer ID as secrets.
2. Pass them to notarytool.
3. Re-submit; authentication should succeed.

xcrun notarytool submit app.zip \
  --key AuthKey.p8 --key-id "$KEY_ID" --issuer "$ISSUER_ID" --wait

Use an app-specific password for Apple ID auth

If authenticating by Apple ID, generate an app-specific password and pass it, not the account password.

xcrun notarytool submit app.zip \
  --apple-id "$APPLE_ID" --password "$APP_SPECIFIC_PW" --team-id "$TEAM_ID" --wait

How to prevent it

• Prefer App Store Connect API keys over Apple ID auth in CI.
• Store the .p8, key ID, and issuer ID as secrets, never inline.
• Use an app-specific password if Apple ID auth is required.

Related guides