apple-app-site-association generator for Universal Links

This tool writes the apple-app-site-association JSON for iOS Universal Links, with webcredentials and App Clips if you need them. It checks your Team ID and bundle ID, supports path exclusions, and lists the hosting rules and Apple CDN caching to expect.

Updated

Ten letters and digits, from developer.apple.com > Membership details.

Exactly as in Xcode: letters, digits, hyphens and dots.

* matches any characters, ? one character. Start a line with ! to exclude it. Add ?name=value or #fragment after a space for query or fragment rules (components only). Order matters: put exclusions first.

Host only. Used for the URL, the entitlement line and the test commands.

apple-app-site-association

{
  "applinks": {
    "details": [
      {
        "appIDs": [
          "ABCDE12345.com.example.app"
        ],
        "components": [
          {
            "/": "/help/website/*",
            "exclude": true
          },
          {
            "/": "/buy/*"
          },
          {
            "/": "/help/*",
            "?": {
              "articleNumber": "????"
            }
          }
        ]
      }
    ]
  },
  "webcredentials": {
    "apps": [
      "ABCDE12345.com.example.app"
    ]
  }
}
App ID
ABCDE12345.com.example.app
Save the file as
apple-app-site-association (no .json extension)
Host it at
https://www.example.com/.well-known/apple-app-site-association
Serve as
HTTPS, valid certificate, HTTP 200, no redirects, Content-Type application/json
Xcode entitlement
applinks:www.example.comand webcredentials:www.example.com
Check your server
curl -sI https://www.example.com/.well-known/apple-app-site-associationExpect 200, application/json and no Location header.
Check what Apple's CDN holds
curl -s https://app-site-association.cdn-apple.com/a/v1/www.example.comDevices read this copy, not your server.
  • Apple's CDN requests the file within 24 hours of the first check and devices look for updates about once a week after install, so a change does not apply instantly.
  • Each subdomain (example.com, www.example.com) needs its own entitlement entry and serves its own copy of this file.

What goes in an apple-app-site-association file?

Universal Links open your website's URLs in your iOS app. Your site proves it allows that by serving a JSON file named apple-app-site-association from /.well-known/ with no extension. The file lists your app by App ID, which is your Team ID, a dot and the bundle ID, and says which URLs it wants.

In the components format each rule is an object: / matches the path, ? matches query items, # matches the fragment, and exclude: true tells the system not to open matching URLs in the app. A comment key is for you and isn't used for matching. The older paths format is a list of path strings where a NOT prefix excludes.

webcredentials lists apps that may use shared web credentials, and appclips lists App Clip IDs. Since iOS 14 and macOS 11, devices don't fetch your file directly: they get it from an Apple-managed CDN, which fetches it within 24 hours, so changes are not instant.

App ID = <Team ID>.<bundle ID>   e.g. ABCDE12345.com.example.app
applinks.details[].components: [{ "/": "/buy/*" }, { "/": "/help/*", "exclude": true }]

What do the components keys mean?

Keys from Apple's Supporting associated domains page, checked 2026-11-11.
KeyMatchesExample
/URL path; * is a wildcard{ "/": "/buy/*" }
?Query items, as name: value{ "?": { "articleNumber": "????" } } (exactly four characters)
#URL fragment{ "#": "no_universal_links", "exclude": true }
excludetrue: do not open as a universal link{ "/": "/help/website/*", "exclude": true }
commentA note for humans, not used to match{ "/": "/buy/*", "comment": "Product pages" }

How to create an apple-app-site-association file

  1. 1
    Enter your IDsFind the 10-character Team ID in your Apple Developer membership details and the bundle ID in Xcode.
  2. 2
    List the pathsOne path per line. Prefix ! to exclude a path, and add ?name=value or #fragment after a space for components rules.
  3. 3
    Save and uploadSave the output as apple-app-site-association with no extension and upload it to /.well-known/ over HTTPS with no redirects.
  4. 4
    Add the entitlement and testAdd applinks:your-domain under Associated Domains in Xcode, then check your server and Apple's CDN copy with the curl commands.

Frequently asked questions

Should the apple-app-site-association file have a .json extension?
No. Apple says to create the file named apple-app-site-association without an extension and place it in /.well-known/. Serve it with an application/json content type; that content type isn't stated on the Apple page we checked, so confirm it against your own response headers.
Why do my Universal Link changes take so long to show up?
Since iOS 14 and macOS 11, apps ask an Apple-managed CDN instead of your server. Apple says the CDN requests your file within 24 hours and devices check for updates about once a week after install.
What is the difference between the components and paths formats?
Components is the format Apple documents now: each rule matches path, query and fragment and can be excluded. The older paths format is a list of path strings with a NOT prefix for exclusions and no query or fragment matching.
Where do I find my Apple Team ID for an app site association file?
In your Apple Developer account under Membership details. It is a 10-character string of uppercase letters and digits, and it comes before the bundle ID in the App ID, like ABCDE12345.com.example.app.
Do I need a separate association file for www and the bare domain?
Yes. Apple says each subdomain needs its own entry in the app's entitlements and has to serve its own association file, so example.com and www.example.com are separate.
How do I stop certain URLs from opening in the app?
Add a component with exclude set to true for that path, for example /help/website/*, and put it before broader rules. In the older paths format, write the path with a NOT prefix.

Sources

Related tools

See all 135 free tools

Need a custom dev tool for your team?

We build internal tools, dashboards, APIs, and SaaS platforms. If you can describe it, we can ship it.

Built by CountryDevs · No signup · No ads · We count visits, never what you enter