Apple Setup

Sign in with Apple domain association: the .well-known file setup

Using Sign in with Apple on the web needs a verification file at /.well-known/apple-developer-domain-association.txt. Where it comes from, how to host it, and the gotchas.

By · · 6 min read

If you use Sign in with Apple on a website — not just inside the iOS app — Apple makes you prove you control the domain before the web flow works. That proof is a verification file hosted at https://yourdomain/.well-known/apple-developer-domain-association.txt. Get the path, content type, or registration order wrong and the web sign-in button fails with an opaque error.

This is where the file comes from, how to host it correctly, and the three gotchas that cause “invalid_client” / “invalid domain” errors.

Note up front: if you only use Sign in with Apple inside the native app, you do not need this file. It’s specifically for the web (JS) flow. For the full submission picture see every URL and file Apple requires for an iOS App Store submission.

When you need it

Sign in with Apple usage Domain association file needed?
Native ASAuthorizationAppleIDProvider in the iOS app only No
Web flow (Sign in with Apple JS) on your site Yes
OAuth-style server-to-server with a Services ID Yes

The file proves to Apple that the domain in your Services ID configuration is one you control, the same way an ACME challenge proves domain control for SSL.

Step 1: Create / configure the Services ID

In the Apple Developer portal → Identifiers → Services IDs:

  1. Create (or edit) a Services ID for your web sign-in.
  2. Enable Sign in with Apple, click Configure.
  3. Add your domain and the return URLs.
  4. Apple generates the content of apple-developer-domain-association.txt for you to download.

Apple’s official walkthrough: Configure Sign in with Apple for the web.

Step 2: Host the file at the exact path

The file must be served at:

https://yourdomain.com/.well-known/apple-developer-domain-association.txt

Requirements Apple verifies:

  • Exact path — .well-known/ directory, exact filename, .txt extension.
  • HTTPS with a valid certificate (no self-signed, no expired).
  • Content-Type: text/plain — some static hosts serve .txt as application/octet-stream; Apple wants text/plain.
  • HTTP 200, no redirects — a 301 to www. or to a CDN host fails verification.
  • Reachable by Apple’s fetcher — no Cloudflare “Under Attack” challenge, no IP allowlist, no Basic Auth.

Verify with curl:

curl -i https://yourdomain.com/.well-known/apple-developer-domain-association.txt
# Expect: HTTP/2 200, Content-Type: text/plain, no Location header

Step 3: Trigger verification

Back in the Services ID configuration, after the file is live, Apple re-fetches it when you save the domain. If it validates, the domain shows as verified and the web sign-in flow works. If not, you’ll see “Verification failed” with no detail — it’s almost always one of the Step 2 requirements.

The three gotchas

1. The www / apex redirect

You host the file at https://yourdomain.com/... but your site redirects apex → www. (or vice versa). Apple follows the literal domain you registered; if that domain 301s, verification fails. Host the file on whichever exact host you put in the Services ID, with no redirect on that path.

2. Wrong Content-Type from a static host

GitHub Pages and some CDNs serve extension-based content types and may not return text/plain for .txt reliably, or strip the .well-known directory. Use a host where you can set headers (Cloudflare Pages _headers, Netlify _headers, Firebase firebase.json, or a purpose-built service). Same class of problem as hosting an AASA file without nginx.

3. Regenerating the Services ID invalidates the old file

If you delete and recreate the Services ID, Apple generates a new file content. The old hosted file no longer matches. Re-download and re-host after any Services ID change.

How OrbitKit handles it

OrbitKit hosts well-known verification files for you at the correct path with the correct Content-Type. You download the apple-developer-domain-association.txt Apple gives you, upload it once, and it’s served at https://yourdomain/.well-known/apple-developer-domain-association.txt on your custom domain — same place as your AASA file, privacy policy, and the rest. Start free or see features.