Implementation
Choosing your RP ID and origins: passkeys across subdomains and domains
6 min read
Key points
- The RP ID must equal the origin's effective domain or be a registrable domain suffix of it, and every passkey is scoped to one RP ID.
- If you have several subdomains, use the shared parent domain (for example example.com) as the RP ID so one passkey works on all of them.
- Sharing passkeys across unrelated domains is possible with related origin requests (/.well-known/webauthn), but check browser support and the label limit first.
Set your passkey RP ID to the host name of your sign-in page or one of its parent domains. If your service spans several subdomains, use the shared parent (for login.example.com and shop.example.com, that is example.com) and the same passkey will work on every one of them. Passkeys are bound to the RP ID they were created with, and changing it later breaks every existing passkey, so decide it once and decide it carefully. For separate domains there is a mechanism called related origin requests, but confirm browser support before you rely on it.
How RP IDs and origins relate
In WebAuthn, a passkey (a public key credential) is scoped to the RP ID (Relying Party Identifier) it was registered with. W3C WebAuthn Level 3 sets these rules:
- An RP ID is based on a domain name. It has no scheme (
https://) and no port - The RP ID must be equal to the caller's origin's effective domain, or a registrable domain suffix of it
- The origin's scheme must be
https. The exception ishttp://localhost - If you don't specify one, the RP ID defaults to the origin's effective domain
The spec's example: for the origin https://login.example.com:1337, valid RP IDs are login.example.com (the default) and example.com. m.login.example.com (a child) and com (a public suffix) are not.
An origin is the scheme, host and port together, and the browser writes it into clientDataJSON on every ceremony. Your server checks that it's an origin you allow. It helps to keep the two ideas apart: the RP ID decides which keys can be used, and the origin check confirms which page made the call.
List every sign-in surface first
Before you pick an RP ID, write down every place where people should be able to sign in with a passkey.
| What to check | Example |
|---|---|
| Hosts that have a sign-in page today | www.example.com, app.example.com |
| Hosts that will get one later | shop.example.com (planned next year) |
| Services on other domains | example-shop.net |
| Native apps | iOS and Android |
| Development and staging | localhost, staging.example.com |
Anything you miss here may end up unable to use the same passkeys.
Pattern 1: a single host
If www.example.com is your only sign-in page, both www.example.com and example.com work as RP IDs. When in doubt, pick the parent, example.com. If you later move or add sign-in to app.example.com, existing passkeys keep working.
With www.example.com as the RP ID, app.example.com can't use those passkeys, because www.example.com is not a suffix of it.
Pattern 2: several subdomains under one parent
For login.example.com, app.example.com and shop.example.com, use example.com. It is a suffix of each host's effective domain, so registration and sign-in work from all of them with the same passkey.
On the server, list the allowed origins explicitly. A loose rule such as "anything ending in example.com" also accepts requests from subdomains that host user content or that you abandoned years ago.
Pattern 3: several unrelated domains
When the registrable domains differ, as with example.com and example-shop.net, the normal rules don't let them share an RP ID. You have three options:
- Centralize sign-in on one domain. Sign in at
login.example.comand hand the session to the other domains through federation such as OpenID Connect. Chrome's developer blog recommends this approach for most sites. - Use related origin requests. Covered below.
- Use a separate RP ID per domain. People then create a separate passkey on each domain.
Related origin requests
WebAuthn Level 3 defines a way for related origins to share one RP ID. You host a JSON file at https://<RP ID>/.well-known/webauthn, served as application/json:
{
"origins": [
"https://example-shop.net",
"https://example.co.uk"
]
}When the RP ID is not a suffix of the page's origin, the browser fetches this file and continues only if the page's origin is listed. Things to keep in mind:
- The spec requires supporting browsers to handle at least five registrable origin labels and leaves the upper limit to browser policy.
example.co.ukandexample.deshare the labelexample. According to web.dev, Chrome's limit is five labels - Chrome added support in 2024 and Safari in 18.0. In browsers without support, passkey use from the other domain fails
- You can check support with
relatedOriginsfromPublicKeyCredential.getClientCapabilities()(the spec recommends that supporting browsers include it)
Keep another sign-in method available so people on unsupported browsers are not locked out.
Native apps
To use the same passkeys in a native app, you also need to associate the app with the domain: Associated Domains (webcredentials) on iOS and Digital Asset Links on Android. Both require a file hosted on the RP ID's domain, so if an app is on your roadmap, choose an RP ID where you can host those files.
Development and staging
http://localhost is allowed without https. But a passkey with the RP ID localhost will not work on example.com in production, and the reverse is also true.
If staging lives at staging.example.com and uses the production RP ID example.com, passkeys created in staging show up as candidates in production, and vice versa. The databases are separate, so picking one fails. Put staging on a different registrable domain (such as example-staging.com) or give it the RP ID staging.example.com.
If you need to change the RP ID
Changing the RP ID makes every registered passkey unusable. If you must do it, plan a period in which everyone creates a new passkey under the new RP ID, and keep another sign-in method available meanwhile. That cost is why it pays to include future hosts in the decision from day one.
Implementing this with SealGate
In SealGate, each project environment (Live and Test) has its own rp_id and allowed origins. Origins must use https (http only for localhost) and be under the rp_id. You can change the rp_id in the environment settings in the dashboard, but registered passkeys stop working when you do (an API key or MCP cannot change it). A new project's Test environment starts with the rp_id localhost and the origin http://localhost:3000. Responses from origins you haven't allowed are rejected with origin_not_allowed (403). See the docs for the settings, and Separating test and live environments for how to split environments.
FAQ
Should my RP ID include www?
It doesn't have to. If you sign in at www.example.com, using example.com as the RP ID lets you add sign-in on other subdomains later without new passkeys.
Does a different port mean a different passkey?
No. RP IDs don't include ports, so the same host on different ports can use the same RP ID. Origins do include the port, though, so allow each one on the server.
Can related origin requests share passkeys across any number of domains?
No. Browsers cap the number of labels, and not every browser supports the feature. Centralizing sign-in on one domain and federating is usually the more dependable choice.
Sources
- Web Authentication: An API for accessing Public Key Credentials Level 3 (W3C, August 25, 2026)
- Allow passkey reuse across your sites with Related Origin Requests (web.dev)
- Introducing hints, Related Origin Requests and JSON serialization for WebAuthn in Chrome (Chrome for Developers, August 30, 2024)
- WebKit Features in Safari 18.0 (WebKit, September 16, 2024)
Related posts
Passkey basics · Implementation
The WebAuthn registration flow: what to check in challenge, options, and verify
A walkthrough of passkey registration (the WebAuthn registration ceremony), covering the options your server builds, navigator.credentials.create(), server-side verification, and what to store, following W3C WebAuthn Level 3.
Implementation · SealGate
How to add passkeys to an existing login without dropping passwords
A step-by-step plan for adding passkeys to a password login you already run, covering the RP ID, enrollment after sign-in, button and autofill sign-in, device management, recovery, and when to retire passwords.
Implementation · SealGate
Passkey sign-in with Next.js (App Router): Route Handlers and autofill
Add passkeys to an existing Next.js App Router login: relay options and verify in a Route Handler, issue your own session, and support autofill and a button.