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 is http://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:

  1. Centralize sign-in on one domain. Sign in at login.example.com and hand the session to the other domains through federation such as OpenID Connect. Chrome's developer blog recommends this approach for most sites.
  2. Use related origin requests. Covered below.
  3. 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:

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.uk and example.de share the label example. 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 relatedOrigins from PublicKeyCredential.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

Related posts

Back to the blog