# Apple App Site Association (AASA) Validator

> Validate your apple-app-site-association file for iOS Universal Links. Check DNS, HTTPS, content-type, JSON format, and signing requirements instantly.

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

Test that your domain serves a valid apple-app-site-association file for Universal Links. We run the same checks Apple uses and show you the parsed JSON.

## Validate Your AASA File

This is an interactive tool: enter your domain at [https://redirectly.app/aasa-validator](https://redirectly.app/aasa-validator) to validate your apple-app-site-association file. The validator checks DNS resolution, HTTPS connectivity, Content-Type headers, and JSON syntax.

## What is an Apple App Site Association (AASA) File?

An Apple App Site Association (AASA) file is a JSON configuration file that iOS and macOS use to verify that your app owns a particular web domain. By hosting this file on your domain, you allow your app to handle Universal Links—HTTPS URLs that open your app instead of Safari when tapped.

The AASA file is a critical part of iOS deep linking infrastructure. Without it, links to your domain will open in Safari instead of launching your app. Apple downloads and validates the AASA file from your domain during app installation, and periodically refreshes it to ensure your app configuration is still valid.

The file must be placed at `/.well-known/apple-app-site-association` on your domain, served over HTTPS, and return the correct `Content-Type` header.

- **Domain Verification** — AASA files prove to iOS that your app is associated with your domain, preventing other apps from hijacking your links.
- **Universal Links** — Enable HTTPS links that seamlessly open your app with zero fallback to the browser when the app is installed.

## How Universal Links Work

Universal Links are the secure, modern way to deep link on iOS. When a user taps a Universal Link (an HTTPS URL), iOS checks if the associated domain has an AASA file that claims the app as an owner. If verified, the link opens the app directly. If the app is not installed, the link opens in Safari.

### The Universal Links Flow

1. **User Installs Your App** — iOS downloads the AASA file from your domain and validates it.
2. **iOS Validates AASA** — Apple checks the file syntax, content type, and your app's bundle ID.
3. **User Taps a Link** — When the user taps an https:// link to your domain, iOS checks if your app is registered.
4. **App Opens or Falls Back** — If your app is installed and claims the domain, it opens. Otherwise, Safari opens the URL.

**Security Benefit:** Unlike custom schemes (myapp://), Universal Links are verified by domain ownership. Apple never routes a Universal Link to the wrong app, eliminating URL scheme hijacking attacks.

## AASA JSON Format Reference

The AASA file is a JSON file with a specific structure. Here's what a typical AASA file looks like and what each field means.

```json
{
  "applinks": {
    "apps": [],
    "details": [
      {
        "appID": "ABCD123456.com.example.myapp",
        "paths": [
          "/account/*",
          "/product/*",
          "NOT /store/*"
        ]
      }
    ]
  },
  "webcredentials": {
    "apps": ["ABCD123456.com.example.myapp"]
  }
}
```

### appID Format

Your app ID consists of your Team ID (from Apple Developer Account) followed by your Bundle Identifier:

```text
ABCD123456.com.example.myapp
```

Team ID (10 chars) + Bundle Identifier = appID

### Paths

Use wildcard patterns to specify which paths your app handles:

- `/product/*` — Matches /product/123, /product/abc, etc.
- `NOT /store/*` — Excludes /store/ paths from your app
- `/*` — Matches all paths

### Sections

- **applinks** — Handles Universal Links to your domain
- **webcredentials** — For password managers and autofill (optional)
- **appclips** — For App Clips (iOS 14+, optional)

## How to Create an AASA File from Scratch

### 1. Find Your App ID

Log in to your Apple Developer Account and go to Identifiers. Find your App ID in the format `ABCD123456.com.example.myapp`. The first 10 characters are your Team ID.

### 2. Create the JSON File

Create a file named `apple-app-site-association` (no .json extension) with this content:

```json
{
  "applinks": {
    "apps": [],
    "details": [
      {
        "appID": "YOUR_TEAM_ID.YOUR_BUNDLE_ID",
        "paths": ["/"]
      }
    ]
  }
}
```

Replace YOUR_TEAM_ID and YOUR_BUNDLE_ID with your actual values.

### 3. Upload to Your Server

Place the file at `/.well-known/apple-app-site-association` on your domain.

For example: `https://redirectly.app/.well-known/apple-app-site-association`

### 4. Configure Server Headers

Ensure your server returns the correct Content-Type header:

```text
Content-Type: application/json
```

### 5. Add Associated Domains to Your App

In Xcode, go to your app target Signing & Capabilities, click "+ Capability" and select Associated Domains. Add your domain with the applinks prefix:

```text
applinks:redirectly.app
```

### 6. Validate with This Tool

Use the AASA Validator to check your file is correctly configured and accessible.

## Common AASA Errors and How to Fix Them

### Wrong Content-Type Header

**Problem:** Server returns text/plain or text/html instead of application/json.

**Fix:** Update your web server configuration. For Apache, add to .htaccess: AddType application/json .well-known/apple-app-site-association. For Nginx, add to your config: types { application/json apple-app-site-association; }

### File Not Found (404)

**Problem:** File is in the wrong location or domain is unreachable.

**Fix:** Ensure the file is at /.well-known/apple-app-site-association on the root of your domain. Verify your domain is accessible over HTTPS without redirects.

### Invalid App ID

**Problem:** appID format is incorrect or missing Team ID.

**Fix:** Use the format XXXXXXXXXX.bundleidentifier where X is your 10-character Team ID. Example: ABCD123456.com.example.myapp

### Malformed JSON

**Problem:** JSON syntax errors prevent parsing.

**Fix:** Validate your JSON using a JSON validator. Check for missing commas, extra quotes, or unclosed brackets.

### HTTPS Redirect Issues

**Problem:** Domain redirects from HTTP to HTTPS or to a different domain.

**Fix:** Apple requires the AASA file to be directly accessible on the exact domain without any redirects. Remove any redirect rules that might affect the /.well-known/ path.

### Associated Domains Not Enabled

**Problem:** App has no Associated Domains capability in Xcode.

**Fix:** In Xcode, select your app target, go to Signing & Capabilities, click + Capability, and add Associated Domains. Add applinks:yourdomain.com for each domain.

### Path Patterns Not Matching

**Problem:** Links to paths not included in the AASA file don't open the app.

**Fix:** Update the paths array in your AASA file. Use * for wildcards (e.g., /product/*) and NOT to exclude paths (e.g., NOT /admin/*).

### File Cached Incorrectly

**Problem:** Changes to the AASA file don't take effect.

**Fix:** Apple caches the AASA file. Reinstall your app on the device, or wait up to 24 hours for the cache to refresh. Clear app data as a workaround.

## Frequently Asked Questions

### Is the AASA file required to use Universal Links?

Yes. Without a valid AASA file on your domain, iOS cannot verify your app owns the domain and will not route Universal Links to your app. The file must be correctly formatted, placed, and served with the right headers.

### How often does Apple check the AASA file?

Apple downloads the AASA file when the app is installed and periodically refreshes it (typically daily). Changes may take up to 24 hours to propagate, though reinstalling the app forces an immediate refresh.

### Can I use the same AASA file for multiple apps?

Yes. Add multiple appID entries in the details array, each with the appropriate bundle identifier and paths. This allows multiple apps to claim the same domain with different path handling.

### What happens if my domain expires or SSL cert lapses?

If your domain becomes inaccessible, iOS cannot verify the AASA file and will stop routing Universal Links to your app. Users will see links open in Safari instead. Restore HTTPS access immediately to restore Universal Links.

### Do I need to test Universal Links on a real device?

Yes. Universal Links only work on actual iOS devices, not simulators. To test, share a link via SMS or email, tap it from a different app, and verify your app opens instead of Safari.

### Can I use subdomains with Universal Links?

Yes. Each subdomain needs its own Associated Domain entry in Xcode (applinks:subdomain.example.com) and a valid AASA file on that subdomain. Subdomains are treated independently.

### What if I need to migrate to a new domain?

Set up the AASA file on the new domain with your app's bundle ID and paths. Update your app to include the new domain in Associated Domains. You can keep the old domain's AASA file for backwards compatibility during the transition.

### Is there a maximum size for the AASA file?

There is no official limit, but keep it minimal. Most AASA files are under 10KB. Avoid adding unnecessary paths or app IDs to keep the file lightweight.

## Related Tools & Resources

- [Asset Links Validator](https://redirectly.app/assetlinks-validator.md) — Validate assetlinks.json for Android App Links and Digital Asset Links.
- [Deep Linking Guide](https://redirectly.app/deep-linking-guide.md) — Complete guide to Universal Links, App Links, and deferred deep linking.
- [Flutter Deep Linking](https://redirectly.app/flutter-deferred-deep-linking.md) — Implement deferred deep linking in Flutter with Redirectly SDK.

---

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