development

AASA (Apple-App-Site-Association)

A JSON file hosted at your domain's .well-known directory that tells Apple which apps are authorized to handle URLs from that domain for Universal Links and App Clips.

associated domains universal links domain verification app clips

The apple-app-site-association (AASA) file is a JSON document that links your web domain to your iOS app. You must host it at https://yourdomain.com/.well-known/apple-app-site-association.

File Structure

A typical AASA file supporting both Universal Links and App Clips:

{
  "applinks": {
    "details": [{
      "appIDs": ["TEAMID.com.yourcompany.yourapp"],
      "components": [
        { "/": "/menu/*" },
        { "/": "/product/*" }
      ]
    }]
  },
  "appclips": {
    "apps": ["TEAMID.com.yourcompany.yourapp.Clip"]
  }
}

Hosting Requirements

  • Served over HTTPS with a valid SSL certificate
  • Content type application/json
  • Accessible without redirects (no HTTP-to-HTTPS redirect in the path)
  • No authentication required
  • File size reasonable (under 128 KB recommended)

Validation

Test your AASA file with:

  • curl -v https://yourdomain.com/.well-known/apple-app-site-association
  • Apple’s AASA validator tools
  • swcutil command-line tool on macOS

CDN Caching

Apple caches AASA files through its own CDN. After an update, changes can take up to 24 hours to propagate. During development, append ?mode=developer to your Associated Domains entitlement to bypass the CDN cache.

Common Mistakes

  • Wrong Team ID prefix (use your Team ID from developer.apple.com, not the App ID prefix)
  • Missing .Clip suffix in the appclips section for App Clip bundle IDs
  • JSON syntax errors (validate with a JSON linter before deploying)
  • Redirects in the server configuration blocking direct access to the file