Join our Newsletter — 33% off our NHI Course
Home› Guides› Sign in with Apple Security Guide: Private Relay…
Guide Customer Identity

Sign in with Apple Security Guide: Private Relay Emails, Token Validation and Account Linking

PDF for newsletter subscribers · free to read online

← All guides
By NHI Mgmt Group, edited by Lalit Choda Updated 14 November 2026 17 min read
On this page

Sign in with Apple hands your service a team-scoped user identifier and, often, an email address that is not the person's real inbox, and most account linking and recovery designs quietly assume the opposite. Teams that treat the relay address as a normal email, key accounts on it, or skip server-side token checks end up with duplicate accounts, broken password resets and orphaned data when a user hides their email, revokes consent or deletes their Apple Account. This guide is for developers, identity architects and customer identity (CIAM) owners who run Sign in with Apple on iOS, macOS or the web. It covers token validation, the relay service, linking and recovery, notifications, revocation, client secrets and app transfers. General social login linking rules are in the Social Login and Account Linking Security Guide; this page goes deeper on the Apple-specific behaviour.

This is an independent guide from NHI Mgmt Group, based on Apple's public documentation as of November 2026. It is not sponsored or reviewed by Apple. Product features change, so confirm settings against Apple's current documentation.

Key takeaways

  • Key every account on sub, never on email. Apple's documentation describes sub as the stable, primary identifier for the user, shared across all apps in your development team and unchanged if the user stops and later resumes using Sign in with Apple.
  • Validate the identity token on your server every time. Check the signature against Apple's published keys (matching kid), iss equal to https://appleid.apple.com, aud equal to your client_id, exp, and the nonce you issued.
  • Treat the relay address as a delivery channel, not an identity. It routes to one of the user's verified addresses, is unique per development team, carries a daily limit of 100 emails, and stops delivering the moment the user turns forwarding off.
  • Subscribe to server-to-server notifications. email-disabled, email-enabled, consent-revoked and account-deleted events tell you when to stop emailing, end sessions or start deletion.
  • Revoke tokens when an account closes. Apple asks apps that support Sign in with Apple to call the REST revoke endpoint during account deletion, so store a refresh token at first sign-in to make that possible.

How Sign in with Apple differs from other social login

Sign in with Apple follows the familiar OAuth 2.0 and OpenID Connect pattern: your app receives an identity token (a signed JWT), a single-use authorisation code, the state from your request and a user identifier. Several behaviours are specific to Apple and drive most of the security design.

BehaviourWhat Apple documentsDesign consequence
Team-scoped identifiersub is the same across all apps of one development team and different for the same person across teamsStore sub as the federated key; plan for app transfers, because a new team sees a new sub
Name and email on first authorisationThe API shares name and email the first time the user signs in; later sign-ins do not ask again, though the email remains in the identity tokenPersist the name immediately and idempotently; a failed first request loses it until the user disconnects and reconnects
Private email relayUsers can share an anonymous address ending in @privaterelay.appleid.com or, for new addresses from late 2026, @private.icloud.com (Apple developer news, 24 August 2026)Email matching to existing accounts fails by design; build an explicit linking step
Two-factor Apple AccountSign-in uses the user's two-factor Apple Account, with Face ID, Touch ID or passcode on Apple devicesA strong first factor, but your own session, step-up and recovery controls still apply
Real user indicatorreal_user_status returns 0 Unsupported, 1 Unknown or 2 LikelyReal, on first sign-in only and only on native platforms from iOS 14 and macOS 11Use it as one fraud signal at account creation, never as a gate
Web versus nativeNative apps allow only the signed-in iCloud user; web interactions allow any Apple AccountWeb flows need state, nonce and redirect URI discipline that native flows partly get from the platform

Whether to offer social sign-in at all is covered in Social Login vs Native Accounts.

Identity token validation on the server

Apple's "Verifying a user" article lists the server checks. Do them in your backend, never only in the client, and reject the sign-in if any fails.

  1. Signature: fetch Apple's JSON Web Key Set from https://appleid.apple.com/auth/keys. Apple notes the endpoint can return several keys and the count varies over time, so select the key whose kid matches the token header. Cache the set and pin the accepted algorithm in your JWT library rather than trusting the header. See the JWT Security Guide.
  2. Issuer: iss must be exactly https://appleid.apple.com.
  3. Audience: aud must be your client_id: the bundle ID for a native app or the Services ID for the web. If you run both, keep an explicit allow-list of your own IDs, not a prefix match.
  4. Expiry: the current time must be earlier than exp.
  5. Nonce: generate a random nonce per sign-in, bind it to the client session, and compare it to the nonce claim. Apple's nonce_supported claim tells you whether the platform supports anti-replay values: if you sent a nonce, the claim is missing and nonce_supported is true, fail the transaction.
  6. Authorisation code exchange: for web apps, Apple says the identity token is obtained by validating the authorisation code at POST https://appleid.apple.com/auth/token with grant_type=authorization_code. The response carries an id_token, a one-hour access token and a refresh token. Include redirect_uri only if your original request did.
  7. Bind state: on the web, compare the returned state with the value stored in the user's pre-authentication session to stop cross-site request forgery on the callback.

Claims to read, and how to read them

ClaimMeaning (per Apple)Safe use
subUnique, stable user identifier for your teamPrimary key of the federated identity record
emailReal address or relay address; Apple says not to use it as an identifierContact channel only
email_verifiedString or Boolean; may be false for Sign in with Apple at Work and School usersParse both forms; never assume true
is_private_emailString or Boolean showing whether the address is the relay proxyDrives your linking and messaging logic
real_user_status0, 1 or 2; native platforms onlyRisk score input at sign-up
transfer_subTransfer identifier, present only during the 60-day transfer periodMap migrated users to new sub values
org_idOrganisation of a Managed Apple Account in Apple School Manager or Apple Business ManagerTenant routing for business and education apps

A common parsing defect is comparing email_verified or is_private_email with a Boolean when the token carries the string "true", or the reverse. Normalise both forms in one function and unit-test it.

The private email relay service

When a user chooses Hide My Email, Apple's relay routes all mail between you and the user through an automatically generated address. Apple documents three properties that matter for security design:

  • Delivery: mail to the relay reaches one of the Apple Account's verified addresses, and replies return through the relay, so the user's real address is never revealed to you.
  • Scope: the address is the same for a user across all apps of one development team and different across teams. Two of your apps see one relay address; a partner company sees another.
  • Limit: each relay address has a daily limit of 100 emails, counting your messages to the address and the user's replies.

Sender registration

To send to relay addresses you must register your outbound email addresses or domains in your Apple developer account and authenticate the mail with SPF. Apple states this ensures only you can reach your users through the channel. In practice:

  • Register every sending path: transactional mail, marketing platforms and support desks often send from different domains or third-party infrastructure. An unregistered sender's mail is not delivered, which surfaces as "password reset never arrived" tickets.
  • Keep SPF, DKIM and DMARC aligned: Apple names SPF; DKIM and DMARC remain good practice for every recipient. See the DMARC, SPF and DKIM Guide.
  • Treat the registration list as a controlled asset: anyone who can add a sender can reach your entire Apple user base through the relay. Restrict who can change it.
  • Budget for the daily limit: notification-heavy products should collapse alerts into digests for relay users rather than risk hitting 100 messages a day and losing a security notice.

When a user stops receiving email from your app, the relay rejects all future messages to that address. Because the address is shared by your team's apps, Apple informs the user of all other affected apps. Your platform learns of it through the email-disabled notification described below.

Account linking when the email is a proxy

Email-based auto-linking, already risky for any provider, simply does not work for relay users: the relay address will never match the address on an existing native account. Apple's own guidance on preventing duplicate accounts suggests two approaches: offer existing keychain credentials through ASAuthorizationPasswordProvider so the user signs in to the account they already have, and, for new Sign in with Apple accounts, tell the user they are creating a new account and ask whether they have an existing one to link.

  • Link only after proving control of both sides: the user signs in with Apple, then authenticates to the existing account with its own credential (password plus MFA, or a passkey). Only then write the sub to the existing account record. Never link on a matching real email shown in the token without that second proof; the general pre-hijacking classes are in the Social Login and Account Linking Security Guide.
  • Store one federated record per provider: a table of (provider, subject, user ID, linked_at, link_method) keeps Apple identities separate from email, so a later change of relay state does not break the link.
  • Record the relay flag: keep is_private_email beside the stored email so support staff and automated jobs know the address is a proxy.
  • Offer a verified contact address: if your service needs a real address (receipts to an accounts team, regulatory notices), ask for it separately and verify it with a one-time link. Keep it distinct from the Apple-supplied address and let the user choose which to use.
  • Unlinking: before letting a user remove Sign in with Apple, require another working sign-in method, or the account becomes unreachable.

Recovery and support when Apple is the only credential

Most recovery flows send a reset link to the account email. For a relay user that link travels through Apple, works only while forwarding is enabled, and lands in an inbox you cannot see. Design for these cases:

SituationWhat happensRecovery design
Forwarding disabledRelay rejects mail; your reset emails and security alerts failOn email-disabled, flag the account and prompt in-app for a verified contact address
Consent revokedCredentials become invalid for your appEnd sessions; on next Apple sign-in the same sub returns, so reattach the existing account
Apple Account deletedApple invalidates all user tokens and disables relay forwarding for all associated appsStart your deletion or dormancy process; there is no Apple path back to this identity
Help desk caller claims to own an accountThe agent sees only a relay address and a subVerify through an in-app or signed-in channel, never by "confirming" a relay address read out on the phone

Help desk social engineering targets exactly these gaps. See the Account Recovery and Help Desk Security Guide for verification scripts.

Server-to-server notifications and session control

Register an endpoint in your developer account to receive Apple's notifications. Apple requires TLS 1.2 or later on the endpoint and allows one URL for several teams and apps. Each notification is a JWS signed by Apple; validate its signature with the same key set as identity tokens, using the algorithm from the header, then act on the type in the events claim.

Event typeMeaningAction
email-disabledUser turned off forwarding to their personal addressSuppress mail to the relay address; request another contact channel in-app
email-enabledUser turned forwarding back onRe-enable mail; keep suppression history for audit
consent-revokedUser stopped using their Apple Account with your app; credentials are invalidRevoke your sessions and refresh tokens for that sub; keep the account for a defined period
account-deletedUser asked Apple to delete their Apple AccountRun your account deletion or retention process for that sub
  • Validate before acting: check signature, iss, aud and iat; deduplicate on jti so a replayed notification cannot repeat a deletion.
  • Native apps: Apple notes that on account deletion the system does not send credentialRevokedNotification to native apps; call getCredentialState(forUserID:completion:), which Apple describes as a local, inexpensive call, and sign the user out when the state changes.
  • Refresh token checks: on other platforms, Apple suggests using periodic refresh token validation to set session lifetime, no more than once a day, as calls may be throttled above that rate.

Token revocation and account deletion

Apple's account deletion guidance says apps that support Sign in with Apple should use the REST API to revoke user tokens. The revoke endpoint is POST https://appleid.apple.com/auth/revoke with your client_id, client_secret, the token, and token_type_hint set to refresh_token or access_token. It returns HTTP 200 with no body when the token is invalidated or was already invalid.

  • Store the refresh token at first sign-in: revocation needs a valid refresh or access token. Encrypt it at rest with a key held in a secrets manager or KMS, scoped to the deletion service.
  • Order the deletion steps: revoke with Apple, end your own sessions, then delete or anonymise data, logging each step against the sub.
  • Handle failure safely: if revocation errors, retry with backoff and alert; do not report deletion complete to the user until it succeeds or a documented manual path is followed.

Where identity fits: the client secret and signing key

Every call to /auth/token and /auth/revoke authenticates your service with a client_secret: a JWT you sign with a private key downloaded from your developer account. Apple's specification is alg ES256, a 10-character kid, iss set to your Team ID, aud set to https://appleid.apple.com, sub set to the App ID or Services ID, and an exp no more than 15777000 seconds (six months) ahead. That private key is a non-human credential with power over your whole Apple user base.

  • Keep the key in a vault or HSM-backed KMS, never in source, mobile binaries or CI variables visible to every job. See the Secrets Management Guide.
  • Mint short-lived client secrets (minutes to hours) on demand, rather than one six-month secret pasted into configuration.
  • Rotate the key when staff with developer account access leave, and revoke unused keys in the developer account.
  • Limit developer account roles, since the same account controls keys, Services IDs, return URLs, notification endpoints and relay sender registration.

App transfers between developer teams

Because sub and relay addresses are team-scoped, moving an app to another team (an acquisition or a reorganisation) changes both. Apple's migration process protects user privacy with a transfer identifier:

  1. Ungroup apps that are grouped for Sign in with Apple; App Store Connect will not transfer an app that is part of a group.
  2. Obtain access tokens: the transferring team can request one with grant_type=client_credentials and scope=user.migration.
  3. Generate transfer identifiers: call POST /auth/usermigrationinfo with each user's sub and the recipient Team ID to receive a transfer_sub.
  4. Export only the transfer identifier: Apple requires the export to exclude the team-scoped identifier and private email address.
  5. Recipient exchanges within 60 days: the recipient must exchange transfer identifiers for its own team-scoped identifiers within 60 days of accepting the transfer; the transfer_sub claim appears in identity tokens only during that period.
  6. Plan email continuity: Apple warns that if a user uses no other app from the transferring team, the transferring team can no longer reach them by relay address after the transfer. Send any required notices before completion.

Track the 60-day deadline as a project milestone and encrypt the export in transit.

Implementation and rollout

  1. Model the data first: federated identity table keyed on (provider, sub), relay flag, verified contact email, encrypted refresh token.
  2. Build server validation with the seven checks above and unit tests for expired tokens, wrong aud, missing nonce and string versus Boolean claims.
  3. Register sender domains and send test mail to a relay address from every system that emails customers.
  4. Stand up the notification endpoint and replay sample payloads in staging to prove each event drives the right action.
  5. Wire revocation into account deletion and test it end to end with a test Apple Account.
  6. Pilot linking and recovery with internal users who choose Hide My Email, then release behind a feature flag. Roll back by disabling new Apple sign-ups while keeping sign-in for existing linked accounts, so no user is locked out.

Detection and measurement

  • Token validation failure rate by reason (signature, aud, exp, nonce). A spike in nonce or aud failures points to replay attempts or a misconfigured client.
  • Relay bounce and rejection rate per sending system; unregistered senders show up here first.
  • Notification processing lag from event_time to completed action; target minutes, not days, for consent-revoked.
  • Duplicate account rate among new Apple sign-ups, measured by later support merges.
  • Revocation success rate on account deletion.
  • Link events logged with method and source IP, alerting on links to high-value accounts shortly after a password reset. Map these to ATT&CK T1078 Valid Accounts and T1550.001 Application Access Token when building detections.

Framework mapping

Control areaNIST SP 800-53 Rev. 5NIST CSF 2.0OWASP ASVS 5.0
Authenticating external users through a federated providerIA-8PR.AA-03OAuth and OIDC chapter
Account lifecycle on revoke and delete eventsAC-2PR.AA-01Authentication chapter
Client secret and signing key managementIA-5, SC-12PR.AA-01Self-contained tokens chapter
Session binding, nonce and stateSC-23, AC-12PR.AA-03Session management chapter
Monitoring link and token eventsAU-6DE.CM-03Logging chapter

Common failure patterns

  • Accounts keyed on email: the user hides their email on a second device or after reconnecting, and a duplicate account appears with no history.
  • Name lost on first sign-in: the backend call fails, the app retries later, and Apple no longer returns the name.
  • Client-only validation: the mobile app decodes the token and posts sub to the API, which trusts it; anyone can then post any sub.
  • Unregistered marketing or support sender: security notices and resets to relay users silently fail.
  • No notification endpoint: consent revocations and account deletions are never processed, leaving live sessions and retained data for people who have left.
  • Six-month client secret in a repository: one leaked file grants token exchange and revocation for every user.

Practitioner checklist

  • Key federated identities on (Apple, sub) and treat email as a contact attribute only.
  • Validate signature by kid, iss, aud, exp, nonce and web state on the server for every sign-in.
  • Persist name, email and relay flag on first authorisation, idempotently.
  • Register every outbound sender for the relay and authenticate with SPF, DKIM and DMARC.
  • Require proof of the existing credential before linking an Apple identity to an account.
  • Run a validated, deduplicated server-to-server notification endpoint for all four event types.
  • Store refresh tokens encrypted and call the revoke endpoint in account deletion.
  • Hold the client secret signing key in a vault or KMS, mint short-lived secrets and rotate on staff change.
  • Plan app transfers around the 60-day transfer_sub window.

Standards and references

Related NHI Mgmt Group resources: Social Login and Account Linking Security Guide · Social Login vs Native Accounts · Apple Platform Security Explained · Customer IAM (CIAM) Guide

PDF for subscribers

Take this guide with you

Every section, table and checklist in one PDF, with links to the sources and related guides. Subscribe to our weekly NHI & AI Identity Journal and we’ll email you a download link.

Free weekly newsletter

Subscribe to the NHI & AI Identity Journal

The latest on NHI and Agentic AI security – articles, research, breaches, news and events every week.

Bonus 33% off our NHI Course when you subscribe.

NHIMG Editorial Note
Researched and written by the NHI Mgmt Group editorial team using AI tools, under the editorial direction of Lalit Choda. Facts are drawn from the sources listed on this page and checked by our automated quality process. Last updated 14 November 2026. Spotted an error? Use our contact page.
NHI Mgmt Group, the independent authority on Non-Human Identity, IAM and Agentic AI security. nhimg.org

PDF Downloads for Newsletter Subscribers

Get the guide

Enter your details and we’ll email you a download link.

The full guide is free to read online. The PDF is a thank you for subscribing.

Fill in all fields marked * and tick the PDF box to continue.