passkeys-restriction.mdx

Passkeys are tied to the domain they are created on and cannot be used across different domains. However, passkeys do work on subdomains if they are registered on the root domain. For example:

• Passkeys created on your-domain.com cannot be used on your-domain-admin.com (different domains).
• Passkeys created on your-domain.com can be used on accounts.your-domain.com (subdomain of the same root domain).
• Passkeys created on staging1.your-domain.com cannot be used on staging2.your-domain.com (sibling subdomains) unless the passkey was scoped to your-domain.com (i.e. the shared root domain).

If you're using satellite domains, in both development and production, passkeys won't be portable between your primary domain and your satellite domains so you should avoid using them.

If you're not using satellite domains:

• In development, you can either:

  • The recommended approach. Use Clerk's components, Elements, or custom flows, instead of the Account Portal. This ensures the passkey is created and used entirely on your development domain, so passkeys created on localhost will only work on localhost.
  • Create a passkey directly through the Account Portal instead of your local application to keep it tied to the Account Portal's domain. Passkeys created on your Account Portal (e.g., your-app.accounts.dev) will only work on that domain, which can cause issues if you switch between localhost and the Account Portal during development. If you choose this approach, ensure all testing happens on the same domain where the passkey was created.

• In production, your Account Portal is usually hosted on a subdomain of your main domain (e.g. accounts.your-domain.com), enabling passkeys to work seamlessly across your app. However, as stated above, if you use satellite domains, passkeys will not work as intended.