Skip to content

Commit 584f18d

Browse files
authored
docs: document custom domain verification files (#1449)
Describe how to host third-party domain ownership verification files on an active Logto custom domain, including path rules and limits.
1 parent bccaf8a commit 584f18d

1 file changed

Lines changed: 29 additions & 0 deletions

File tree

docs/logto-cloud/custom-domain.mdx

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,7 @@ Your custom domains are used for several functions:
1818
- Callback URIs for [social connectors](/connectors/social-connectors) or [enterprise SSO connectors](/connectors/enterprise-connectors).
1919
- [Passkey](/end-user-flows/mfa/webauthn) and [passkey sign-in](/end-user-flows/sign-up-and-sign-in/passkey-sign-in) related URLs (Changing the domain after users have linked Passkeys may block both MFA and sign-in with those credentials).
2020
- [SDK endpoint](/integrate-logto/application-data-structure#openid-provider-configuration-endpoint) for integrating Logto with your application.
21+
- Domain ownership verification files for third-party platforms (for example WeChat, Apple, or other services that require a static file on your domain).
2122

2223
## Multiple custom domains \{#multiple-custom-domains}
2324

@@ -57,6 +58,34 @@ To add a new custom domain in the Logto Console, follow these steps:
5758

5859
To add multiple custom domains, simply repeat the above steps for each domain you want to configure.
5960

61+
## Domain verification files \{#domain-verification-files}
62+
63+
Some third-party platforms require you to host a small text or JSON file on your domain to prove ownership before you can use their OAuth, SSO, or other integrations. Because a Logto custom domain points to Logto Cloud, you cannot upload that file to your own origin. Logto can host those files for you.
64+
65+
After a custom domain is **Active**, open the domain card in <CloudLink to="/tenant-settings/domains">Console > Settings > Domains</CloudLink> and use the **Domain verification files** section to add, update, or remove files.
66+
67+
**Supported paths**
68+
69+
- Root-level filenames with an extension, such as `/MP_verify_xxx.txt` or `/apple-developer-domain-association.txt`
70+
- Paths under `/.well-known/`, such as `/.well-known/apple-developer-domain-association.txt`
71+
72+
Only letters, numbers, dots, hyphens, and underscores are allowed in path segments. Nested paths outside `/.well-known/` are not supported.
73+
74+
**Limits**
75+
76+
- Up to **10** verification files per custom domain
77+
- Content size up to **16,384** characters per file
78+
- Content type: plain text (`text/plain`) or JSON (`application/json`)
79+
80+
Once saved, Logto serves an exact match for `GET` and `HEAD` requests on the custom domain, for example:
81+
82+
```
83+
https://auth.example.com/MP_verify_xxx.txt
84+
https://auth.example.com/.well-known/apple-developer-domain-association.txt
85+
```
86+
87+
Existing Logto routes always take precedence. Verification files are only served when no other Logto handler matches the path.
88+
6089
## Troubleshooting \{#troubleshooting}
6190

6291
<details>

0 commit comments

Comments
 (0)