Hi. Is it possible to set a

/.well-known/apple-app-site-association

file for our Descope custom sub-domain directly with Descope? It seems like we need that in order to support biometrics (passkeys) in our native iOS app which simply displays our website (Next.js, with the Descope component) via a web view.

Apple App Site Association File Limitations Descope doesn't provide direct configuration of

/.well-known/apple-app-site-association

files on custom domains. This file must be served from your own infrastructure. Recommended Approach for iOS WebView Passkeys 1. Host the file yourself - Create the Apple App Site Association file on your web server - Serve it from

<https://yourdomain.com/.well-known/apple-app-site-association>

- Ensure your domain matches the one configured in Descope passkey settings 2. Configure iOS app associated domains - Add

webcredentials:<http://yourdomain.com|yourdomain.com>

to your iOS app's associated domains - This must match the top-level domain configured in Descope console

{
  "webcredentials": {
    "apps": [
      "TEAMID.com.yourcompany.yourapp"
    ]
  }
}

Alternative Solutions • Use Descope's native iOS SDK instead of WebView for better passkey integration • Consider implementing passkeys through your main app domain rather than the Descope custom subdomain The Apple App Site Association file requirement is an iOS security feature that cannot be bypassed or managed directly through Descope's infrastructure. Passkeys with Mobile SDK | Descope Documentation

apple-app-site-association

files have to be define for each sub-domain. Our web app is on www.ourdomain.com while Descope is configured to use auth.ourdomain.com

Hi, I'm Descope's AI assistant. Domain Mismatch Issue You're correct — passkeys require the Apple App Site Association file on the exact domain where authentication occurs. Since your Descope flows run on

<http://auth.ourdomain.com|auth.ourdomain.com>

but your app is on

<http://www.ourdomain.com|www.ourdomain.com>

, you need the file on both domains. Required Configuration 1. Add the file to auth.ourdomain.com - Contact Descope support to request Apple App Site Association file hosting on your custom domain - Alternatively, use a reverse proxy/CDN to serve the file from

<https://auth.ourdomain.com/.well-known/apple-app-site-association>

2. Add the file to www.ourdomain.com - Host the same Apple App Site Association file on your main domain - Both domains should reference your iOS app's Team ID and Bundle ID

{
  "webcredentials": {
    "apps": [
      "TEAMID.com.yourcompany.yourapp"
    ]
  }
}

iOS App Configuration Add both domains to your app's associated domains:

webcredentials:<http://www.ourdomain.com|www.ourdomain.com>
webcredentials:<http://auth.ourdomain.com|auth.ourdomain.com>

Alternative Approach Consider configuring Descope to use

<http://www.ourdomain.com|www.ourdomain.com>

as both your app domain and custom auth domain, then route

/auth/*

paths to Descope. This eliminates the domain mismatch entirely. The key requirement is that the domain serving passkey authentication (where WebAuthn API calls occur) must have the Apple App Site Association file configured . Passkeys with Mobile SDK | Descope Documentation

@Michael Rimboim - can you help here? I know you've gone over this with a customer previously

Hi @Noel, pleasure to meet you. You actually do not need to set the

apple-app-site-association

on the custom CNAME domain that points to Descope. You can set it on you top level domain since you have access to change the relying party/passkey domain to be you top level as well, setting is in auth methods - passkeys>. While your hosted page you use for the native flows on mobile is auth.ourdomain.com, the passkeys will actually take place on ourdomain.com so when apple/android goes to do verification it is looking for ourdomain.com/.well-known/apple-app-site-association which you should be able to hose with a public route. 1. Host well-known folder and association file on your top level domain and public route, in your next-js. So https://ourdomain.com/.well-known/apple-app-site-assocaiton 2. Set the domain of the passkey in the descope auth method to be ourdomain.com not auth.ourdomain.com 3. Validate that is is hosted correctly and accessible using any of the following tools: https://docs.median.co/docs/deep-linking-validator or https://branch.io/resources/aasa-validator/. You would input ourdomain.com