What is an apple-app-site-association file?

An apple-app-site-association (AASA) file is a JSON file that Apple requires you to host on your domain at /.well-known/apple-app-site-association. It tells iOS which apps are allowed to handle Universal Links for your domain.

Where should I place the apple-app-site-association file?

The AASA file must be placed at /.well-known/apple-app-site-association on the root of your domain. For example, if your domain is example.com, the file should be accessible at https://example.com/.well-known/apple-app-site-association.

What is the correct content type for the AASA file?

The AASA file must be served with the Content-Type header set to application/json. Without the correct content type, Apple will reject the file and Universal Links will not work.

How do I create an apple-app-site-association file?

Create a JSON file with your app ID (team ID + bundle identifier) and the paths your app handles. Include applinks, webcredentials, and appclips objects as needed. Upload it to /.well-known/apple-app-site-association and ensure it's served over HTTPS with the correct content type.

What is the difference between Universal Links and regular deep links?

Universal Links use HTTPS and require an AASA file to verify domain ownership. Regular deep links are app-defined and can use custom schemes. Universal Links are more secure because they require domain verification, preventing other apps from hijacking your links.

Does the AASA file need to be signed?

No, the AASA file does not need to be cryptographically signed. Apple validates the file by checking the domain ownership and verifying the HTTPS connection. However, it must be served over HTTPS and not be redirected.

What are common reasons Universal Links fail?

Common issues include: AASA file not served with application/json content type, file placed in wrong location, missing or incorrect app ID format, incorrect path syntax, AASA file validation errors, or cached versions. Use an AASA validator to check your setup.

How do I test if my Universal Links are working?

Test by tapping a Universal Link from Safari. If configured correctly, the app opens directly without showing the browser. You can also use an AASA validator tool to check the file format and ensure it's correctly published.

AASA Validator — Apple App Site Association Checker | Redirectly

Basics

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.

Deep Linking

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.

Technical

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.

{
  "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:

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

applinksHandles Universal Links to your domain
webcredentialsFor password managers and autofill (optional)
appclipsFor App Clips (iOS 14+, optional)

How-To

How to Create an AASA File from Scratch

1Find 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.

2Create the JSON File

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

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

Replace YOUR_TEAM_ID and YOUR_BUNDLE_ID with your actual values.

3Upload to Your Server

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

For example: https://yourapp.com/.well-known/apple-app-site-association

4Configure Server Headers

Ensure your server returns the correct Content-Type header:

Content-Type: application/json

5Add 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:

applinks:yourapp.com

6Validate with This Tool

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

Tool

Validate Your AASA File

Enter your domain below to validate your apple-app-site-association file. The validator checks DNS resolution, HTTPS connectivity, Content-Type headers, and JSON syntax.

Enter your website domain below. We'll fetch your apple-app-site-association file from /.well-known/apple-app-site-association and run the same checks Apple uses for Universal Links. If Universal Links still don't work, also verify your Xcode project's Associated Domains and entitlements.

Domain / Web Page

This tool is not affiliated with Apple. It helps you verify that your AASA file is reachable and valid for Universal Links. For issues with your app configuration, see Apple's documentation on Associated Domains.

Troubleshooting

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.

FAQ

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

Explore our other validation tools and deep linking resources.

Asset Links Validator

Validate assetlinks.json for Android App Links and Digital Asset Links.

Deep Linking Guide

Complete guide to Universal Links, App Links, and deferred deep linking.

Flutter Deep Linking

Implement deferred deep linking in Flutter with Redirectly SDK.

Apple App Site Association (AASA) Validator