1. Introduction
This section is non-normative.
WebAuthn Relying Parties (RPs) currently lack a way to programmatically advertise that they support passkeys, where a user can create a passkey for the service and where they can manage existing passkeys for the service. Passkeys can also be used for additional functions beyond sign in, such as signing and encryption. By proposing a well-known URL which defines a set of passkey-specific endpoints, this specification enables WebAuthn Clients and credential managers (authenticators) to link directly to workflow-specific and informational endpoints instead of the user needing to dig through their account settings and help pages.
2. Infrastructure
This specification depends on the Infra Standard. [INFRA]
This specification uses terminology from the Fetch, HTML, HTTP, and URL standards. [FETCH] [HTML] [HTTP-SEMANTICS] [URL]
3. Passkey Endpoints URLs
To advertise support for passkeys and/or provide direct endpoints for passkey creation and management, Relying Parties MUST host a JSON document at the path formed by concatenating the string .well-known/passkey-endpoints with the https scheme and relying party identifier as per [WELL-KNOWN]. A redirect MUST not be returned.
The passkey endpoints URL for RP ID "example.com" is "https://example.com/.well-known/passkey-endpoints".
3.1. Server Response
The server in this context is a WebAuthn Relying Party (RP) supporting passkeys.
A successful response MUST use the 200 OK HTTP status code and return a JSON object using the application/json content type.
The returned JSON object can contain any of the members defined below.
- enroll
-
This OPTIONAL member contains a direct URL to the passkey creation page for a user account
- manage
-
This OPTIONAL member contains a direct URL to the passkey management page for a user account
- prfUsageDetails
-
This OPTIONAL member contains a URL to an informational page describing how the RP uses the WebAuthn Pseudo-Random Function Extension (PRF).
HTTP / 1.1 200 OK Content-Type : application/json { "enroll" : "https://example.com/account/manage/passkeys/create" , "manage" : "https://example.com/account/manage/passkeys" , "prfUsageDetails" : "https://example.com/help/passkeys#encryption" }
An empty JSON object CAN be returned to signal support for passkeys, but not advertise specific endpoints.
3.2. Client Processing
A client in this context can be either a WebAuthn WebAuthn Client or a credential manager (authenticator).
Given a passkey’s relying party identifier, generate a passkey endpoints URL by running these steps:
-
Let url be a new
URLwith values set as follows:- scheme
-
"https"
- host
-
the passkey’s relying party identifier
- port
-
null
- path
-
« ".well-known", "passkey-endpoints" ».
-
Return url.
The passkey endpoints URL for RP ID "example.com" is "https://example.com/.well-known/passkey-endpoints".
4. Usage by WebAuthn Clients and Credential Managers
This section is non-normative.
enroll
Passkey enrollments are typically driven by an RP’s business logic and session context. Sometimes it can happen after a user successfully signs in with a password or goes through a password reset flow and other times when a user visits a dedicated "passkey creation" page.
These passkey creation entry points can be difficult for users to find, as they’re often buried inside account settings or help pages.
Sample usage when this member is present:
-
Credential managers can show a "passkey upgrade available" button in a given account entry, taking the user directly to the RP’s passkey creation page in their default browser.
-
Credential managers can provide a passkey upgrade flow after detecting a user sign in with a password by showing a notification to the user, which when clicked, takes the user directly to the RP’s passkey creation page in their default browser.
-
WebAuthn clients can provide a passkey upgrade flow after detecting a user sign in with a password by showing a notification to the user, which when clicked, takes the user directly to the RP’s passkey creation page.
manage
Credential management is often buried inside account settings, which can be difficult for users to find.
When this member is present, credential managers can display a direct link to the RP’s passkey (or general credential management) page.
prfUsageDetails
Some Relying Parties (RPs) use the WebAuthn Pseudo-Random Function (PRF) Extension to sign or encrypt user data. Since passkeys are primarily designed for authentication, users may be unaware that deleting a PRF-enabled passkey could affect their saved data or other functionality.
RPs leveraging PRF should provide a dedicated informational page detailing how their passkeys are used beyond authentication and the implications of deletion. This page’s URL should be the value of the prfUsageDetails key.
When this member is present, credential managers should display a warning during the passkey deletion flow, including a link to the RP’s informational page.
5. IANA considerations
5.1. The passkey-endpoints well-known URI
This document defines the ".well-known" URI passkey-endpoints.
This registration will be submitted to the IESG for review, approval, and registration with IANA using the template defined in [WELL-KNOWN] as follows:
- URI suffix
-
passkey-endpoints
- Change controller
-
W3C
- Specification document(s)
-
This document is the relevant specification. (See § 3.1 Server Response)
- Related information:
-
None.
Acknowledgements
Thanks to Arnar Birgisson, Rew Islam, Adam Langley, René Léveillé, Matthew Miller, Ricky Mondello, and Dan Veditz for their feedback on this proposal.