# Apple App Site Association (AASA)

> A JSON configuration file hosted on a web domain that tells iOS which URL paths should open in a native app, enabling Universal Links.

- Canonical: https://redirectly.app/glossary/aasa
- Site: [Redirectly](https://redirectly.app) — deferred deep linking for Flutter & React Native

## Definition

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

## FAQ

### 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](https://redirectly.app/glossary/universal-links.md)
- [Deep Linking](https://redirectly.app/glossary/deep-linking.md)
- [Android App Links](https://redirectly.app/glossary/android-app-links.md)
- [URI Schemes](https://redirectly.app/glossary/uri-schemes.md)

## Related pages

- [AASA Validator Tool](https://redirectly.app/aasa-validator.md)
- [AASA File Errors (Debug)](https://redirectly.app/debug/aasa-file-errors.md)
- [AASA File Format Guide](https://redirectly.app/blog/aasa-file-format-ios-guide.md)
- [Universal Links Not Working](https://redirectly.app/debug/universal-links-not-working.md)

---

Full site index for AI agents: https://redirectly.app/llms.txt