What the AASA File Does
The Apple App Site Association file is the handshake between your website and your iOS app. Universal Links only open an app if both sides agree: the app declares the domain in its Associated Domains entitlement, and the domain declares the app in its AASA file. If either side is missing or wrong, iOS opens the link in Safari instead.
That two-way check is what makes Universal Links safer than custom URL schemes. Any app can register myapp://, but only the owner of example.com can publish a file on example.com that names a specific app. iOS trusts the file because it came from the domain over HTTPS.
The same file can declare more than Universal Links. The webcredentials key lets iOS offer saved passwords from your website inside your app, and the appclips key ties App Clip experiences to your domain.
File Format and Hosting Rules
The file lives at /.well-known/apple-app-site-association on each domain or subdomain you want to handle. It has no file extension, must be served over HTTPS with a valid certificate, must not redirect, and should return Content-Type: application/json. It must stay under 128 KB.
The modern format, supported since iOS 13, looks like this in outline. An applinks object contains a details array. Each entry has an appIDs array (your Team ID, a dot, then the bundle ID) and a components array. Each component can match a path with /, a query with ?, or a fragment with #, and can set exclude: true to keep a path on the web. Wildcards use * for any characters and ? for a single character. Order matters: iOS stops at the first matching component, so exclusions should come before broad matches.
Older apps may still ship the legacy paths array. iOS still reads it, but components give finer control and are the format to use for new setups.
How iOS Fetches and Caches It
Since iOS 14, devices do not contact your server for the file. Apple's CDN at app-site-association.cdn-apple.com fetches your AASA file, caches it, and serves it to devices when an app with that associated domain is installed or updated. This protects your server from traffic spikes, but it also means changes are not instant. An edit you deploy today may take a while to reach devices, and a device that installed the app before the edit can keep the old version until the app updates.
For development, append ?mode=developer to the domain in the Associated Domains entitlement and enable associated domains development in the device's developer settings. The device then fetches the file directly from your server, which makes testing changes practical. Remove the mode before shipping to the App Store.
The CDN also needs to reach your file. Domains behind login walls, IP allowlists, geo-blocks or bot protection that challenges Apple's crawler will fail verification even if the file looks fine in your browser.
Validating Your AASA File
Most Universal Link bugs trace back to the AASA file, and most are easy to catch with a check. Confirm the file returns 200 at the exact path, with no redirect from http to https or from the bare domain to www. Confirm the content type, that the JSON parses, that the Team ID and bundle ID match your app, and that the paths you use in campaigns actually match a component.
The free AASA validator runs these checks against any domain and points to the line that is wrong. Run it after every deploy that touches the file, after changing domains, and whenever links that used to open the app start opening Safari.
When a deep linking provider serves links on your branded domain, the provider should host and update this file for you. Linkrunner hosts the AASA and assetlinks.json files for your link domain, so verification stays correct when you add apps or change paths. See deep linking for how branded domains are set up.
Common Mistakes
Serving the file through a redirect is the most frequent failure. Many sites redirect every request to www or add a trailing slash, and iOS will not follow either redirect for this file.
A wrong app identifier is second. The Team ID prefix must be the ten-character ID from your Apple developer account, not the app's name or the App Store ID. Apps with several bundle IDs for staging and production need each one listed.
Overly broad matches cause the opposite problem: links that should open on the web, such as help pages or password resets, open the app instead. Add explicit exclusions for web-only paths.
Finally, remember that iOS ignores Universal Links in some situations by design, such as when a user pastes a URL into Safari's address bar or when a link redirects across domains before reaching yours. Test by tapping links from Notes or Messages on a physical device.