Apple App Site Association validator
Your apple-app-site-association file must be valid JSON, served over HTTPS at /.well-known/apple-app-site-association with no redirect, and list each app as TEAMID.bundle.id. Paste the file below to find JSON and structure errors, then type a URL to see which rule matches first and whether the link opens your app.
1. Check how your server sends the file
2. Paste or drop your file
You can also drop the downloaded file on the box.
3. Test a URL
Paste a valid file in box 2 first.
Each entry is checked on its own, rules in order, first match wins. Matching was checked against Apple's swcutil tool. A real device also needs the Associated Domains entitlement, a reachable file, and Apple's CDN to have fetched it.
Rules checked against Apple's documentation and swcutil on 2026-10-30.
How it works
- •The JSON is read by a strict parser on this page, so an error shows its line and column and a reason, such as a trailing comma or single quotes.
- •The structure is checked against Apple's applinks reference: details with appIDs and components (/, ?, #, exclude, comment, caseSensitive, percentEncoded), defaults, substitutionVariables, the older appID and paths format, and the apps lists of webcredentials and appclips.
- •The URL tester follows Apple's rules: entries and rules are read in order and the first match wins; * matches any run of characters, ? exactly one and ?* at least one. Where Apple's text is silent, such as trailing slashes, a missing query item or percent-encoding, the behaviour was measured with Apple's swcutil tool and copied here.
- •Browsers cannot read another site's file, so for hosting the page gives you curl commands for your domain and reads their output: status, redirects and Content-Type.
- •Nothing is uploaded: the text you paste is checked in your browser.
What it does not do
- •It does not fetch your file or test your HTTPS certificate. Run the curl commands shown for that.
- •It does not see Apple's CDN, which can take up to a day to fetch a new file, or devices, which check about once a week.
- •It cannot check that your app has the matching Associated Domains entitlement or that the Team ID belongs to you.
- •Apple's current pages do not give a size limit or content type. The 128 KB limit and application/json come from Apple's older Universal Links guide and are shown as warnings.
- •Rules were checked against Apple's documentation and the swcutil tool on 2026-10-30.
Questions
- Where must the apple-app-site-association file be?
- At https://your-domain/.well-known/apple-app-site-association, with no .json extension, over HTTPS with a valid certificate and no redirects. Each subdomain in your entitlement, such as www.example.com, needs its own file. A file on example.com also covers a wildcard entry like applinks:*.example.com.
- Why do my universal links open Safari instead of my app?
- Common causes: the file is redirected or blocked (403, 404), the app ID has the wrong Team ID, an exclude rule matches first, or the link is on the same domain as the page you are on (Safari then stays in the browser). Typing a URL in the address bar never opens the app. Long-press the link in Notes to test.
- What is the difference between appIDs/components and appID/paths?
- appIDs with components is the current format and can match the path, query and fragment. appID with paths is the older format, which matches the path only and uses a "NOT " prefix to exclude. Apple still accepts both but asks you not to mix them in one entry.
- Does "/buy/*" also match /buy?
- Yes. When we tested with Apple's swcutil, trailing slashes did not matter: "/buy/*" matched /buy and /buy/, and "/help" matched /help/. Use "/buy/?*" if you need at least one more character after the slash.
- How long until a changed file takes effect?
- Since iOS 14 and macOS 11, devices get the file from Apple's CDN, which requests it within 24 hours. Devices check for updates about once a week after the app is installed; reinstalling the app fetches it again. For testing, Apple's developer mode (?mode=developer in the entitlement) reads your server directly.
- Does the AASA file need to be signed?
- No. Since iOS 9 a plain JSON file served over HTTPS is enough. Signing was only needed for Handoff and web credentials on iOS 8.