What is Apple App Site Association (AASA)?
The Apple App Site Association (AASA) file is a JSON configuration file that establishes a verified link between a web domain and one or more iOS apps. It is the cornerstone of Universal Links on iOS — without a valid AASA file, Universal Links cannot function.
The AASA file is hosted at a well-known path on your domain: `https://yourdomain.com/.well-known/apple-app-site-association`. It must be served over HTTPS with the correct content type and without any redirects. Apple's CDN fetches this file when a user installs your app to verify the domain-app association.
How it works
The AASA file contains a JSON object that specifies which apps are associated with your domain and which URL paths each app can handle:
File location — Must be at /.well-known/apple-app-site-association (no file extension).
Content type — Must be served as application/json.
App association — Each entry includes your team ID and bundle ID in the format TEAMID.com.example.app, plus an array of URL path patterns the app handles.
Pattern matching — Supports wildcards (*) and exclusion patterns (NOT). For example, /products/* matches any product URL, while NOT /products/admin/* excludes admin paths.
Apple CDN caching — Apple fetches the AASA file through its own CDN (app-site-association.cdn-apple.com) and caches it. Changes may take 24-48 hours to propagate. In iOS 14+, Apple introduced an alternate CDN endpoint that updates more frequently.
Why it matters
The AASA file is a critical piece of your mobile deep linking infrastructure:
- Required for Universal Links — No AASA file means no Universal Links functionality on iOS - Security verification — Proves domain ownership to Apple, preventing unauthorized apps from intercepting your URLs - Flexible path matching — Control exactly which URLs open your app and which stay in Safari - Multiple app support — A single domain can associate with multiple apps (e.g., main app and lite version) - Shared Web Credentials — AASA also enables AutoFill of passwords between your website and app
Frequently asked questions
How do I create an AASA file?
Create a JSON file with the applinks key containing your app's team ID and bundle ID, plus the URL paths to handle. Host it at /.well-known/apple-app-site-association on your domain over HTTPS. Use Redirectly's AASA Validator to verify your file is correct before deploying.
Why are my Universal Links not working after updating the AASA file?
Apple caches AASA files through its CDN, so changes can take 24-48 hours to propagate. Other common issues include: serving the file with redirects (not allowed), incorrect content type, invalid JSON syntax, or mismatched team/bundle IDs. Use an AASA validator to diagnose the specific issue.
Does the AASA file need a .json extension?
No. The AASA file must NOT have a file extension. It should be served at the exact path /.well-known/apple-app-site-association with the application/json content type. Adding a .json extension will cause Universal Links to fail.
Related terms
Universal Links
An iOS feature that allows HTTPS URLs to open directly in a native app instead of Safari, verified through an Apple App Site Association (AASA) file.
Deep Linking
A technique that uses URIs to link directly to a specific screen or piece of content within a mobile app, rather than simply launching the app's home screen.
Android App Links
Android's verified deep linking mechanism that uses Digital Asset Links to associate HTTPS URLs with an app, allowing links to open directly in the app without a disambiguation dialog.
URI Schemes
Custom URL protocols (like myapp://path) that enable basic deep linking into mobile apps, though without the security and fallback benefits of Universal Links or App Links.