A Well-Known URL for Changing Passwords

W3C First Public Working Draft,

More details about this document
This version:
Latest published version:
Editor's Draft:
public-webappsec@w3.org with subject line “[change-password-url] … message topic …” (archives)
Inline In Spec
(Apple Inc.)
(Apple Inc.)


This specification defines a well-known URL that sites can use to make their change password forms discoverable by tools. This simple affordance provides a way for software to help the user find the way to change their password.

Status of this document

This section describes the status of this document at the time of its publication. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at https://www.w3.org/TR/.

This document was published by the Web Application Security Working Group as a First Public Working Draft using the Recommendation track. This document is intended to become a W3C Recommendation.

The (archived) public mailing list public-webappsec@w3.org (see instructions) is preferred for discussion of this specification. When sending e-mail, please put the text “change-password-url” in the subject, preferably like this: “[change-password-url] …summary of comment…

Publication as a First Public Working Draft does not imply endorsement by W3C and its Members. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.

This document was produced by the Web Application Security Working Group.

This document was produced by a group operating under the W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.

This document is governed by the 2 November 2021 W3C Process Document.

1. Introduction

This section is non-normative.

Client-side password management software helps improve both the security and usability of websites which require authentication. It improves security by reducing cross-site password reuse, and enhances usability by providing autofill functionality.

Sites currently lack a way to programmatically advertise where a user can change their password. By proposing a well-known URL for changing passwords, this specification enables password managers to help users change their passwords on sites which support it.

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. Change Password URLs

A change password url of an origin is a URL that points to a resource that clients can use to discover where a user should go to update their password on origin.

Given an origin, clients generate a change password url by running these steps:

  1. If origin is not a potentially trustworthy origin, return failure.

  2. Assert: origin is a tuple origin.

  3. Let url be a new URL with values set as follows:


    origin’s scheme


    origin’s host


    origin’s port


    « ".well-known", "change-password" ».

  4. Return url.

The change password url for origin "https://example.com/" is "https://example.com/.well-known/change-password".

Servers should redirect HTTP requests for an origin’s change password url to the actual page on which users may change their password by returning a response with a redirect status of 302, 303, or 307, and a Location header. [FETCH] [HTTP-SEMANTICS] Clients must handle such redirects when requesting a change password url.

Note: The above paragraph restricts servers to using temporary redirect codes. See Issue 13.

If necessary, servers may respond with an HTML document containing an http-equiv pragma directive in the refresh state. [HTML] Clients should handle such redirects when requesting a change password url.

Servers must not locate the actual change password page at the change password url, per RFC8615 §1.1 Appropriate Use of Well-Known URIs. Clients must handle ok status responses when requesting a change password url.

Note: Implementations might want to use ToUnicode when displaying change password urls. [IDNA]

Make use of test the reliability of an origin’s response status codes from [RESPONSE-CODE-RELIABILITY].

4. IANA considerations

4.1. The change-password well-known URI

This document defines the “.well-known” URI change-password. 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


Change controller


Specification document(s)

This document is the relevant specification. (See § 3 Change Password URLs)

Related information:



Thanks to Anne van Kesteren, Cl1608Ho, Dan Bernstein, David Singer, Dean Jackson, Florian Rivoal, John Wilander, Maciej Stachowiak, Mark Nottingham, Mike West, and Ricky Mondello for their feedback on this proposal. All of its features are theirs and all of its bugs are mine.


Document conventions

Conformance requirements are expressed with a combination of descriptive assertions and RFC 2119 terminology. The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in the normative parts of this document are to be interpreted as described in RFC 2119. However, for readability, these words do not appear in all uppercase letters in this specification.

All of the text of this specification is normative except sections explicitly marked as non-normative, examples, and notes. [RFC2119]

Examples in this specification are introduced with the words “for example” or are set apart from the normative text with class="example", like this:

This is an example of an informative example.

Informative notes begin with the word “Note” and are set apart from the normative text with class="note", like this:

Note, this is an informative note.

Conformant Algorithms

Requirements phrased in the imperative as part of algorithms (such as "strip any leading space characters" or "return false and abort these steps") are to be interpreted with the meaning of the key word ("must", "should", "may", etc) used in introducing the algorithm.

Conformance requirements phrased as algorithms or specific steps can be implemented in any manner, so long as the end result is equivalent. In particular, the algorithms defined in this specification are intended to be easy to understand and are not intended to be performant. Implementers are encouraged to optimize.


Terms defined by this specification

Terms defined by reference


Normative References

Anne van Kesteren. Fetch Standard. Living Standard. URL: https://fetch.spec.whatwg.org/
Anne van Kesteren; et al. HTML Standard. Living Standard. URL: https://html.spec.whatwg.org/multipage/
R. Fielding, Ed.; M. Nottingham, Ed.; J. Reschke, Ed.. HTTP Semantics. June 2022. Internet Standard. URL: https://www.rfc-editor.org/rfc/rfc9110
Anne van Kesteren; Domenic Denicola. Infra Standard. Living Standard. URL: https://infra.spec.whatwg.org/
Ricky Mondello; Theresa O'Connor. Detecting the reliability of HTTP status codes. CG-DRAFT. URL: https://wicg.github.io/change-password-url/response-code-reliability.html
S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Best Current Practice. URL: https://datatracker.ietf.org/doc/html/rfc2119
R. Fielding, Ed.; J. Reschke, Ed.. Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content. June 2014. Proposed Standard. URL: https://httpwg.org/specs/rfc7231.html
Mike West. Secure Contexts. 18 September 2021. CR. URL: https://www.w3.org/TR/secure-contexts/
Anne van Kesteren. URL Standard. Living Standard. URL: https://url.spec.whatwg.org/
M. Nottingham. Well-Known Uniform Resource Identifiers (URIs). May 2019. Proposed Standard. URL: https://www.rfc-editor.org/rfc/rfc8615

Informative References

Mark Davis; Michel Suignard. Unicode IDNA Compatibility Processing. 26 August 2022. Unicode Technical Standard #46. URL: https://www.unicode.org/reports/tr46/tr46-29.html

Issues Index

Make use of test the reliability of an origin’s response status codes from [RESPONSE-CODE-RELIABILITY].