# Document Shepherd Write-Up for draft-ietf-httpapi-privacy
**Document Shepherd:** Darrel Miller
**Date:** November 23, 2025
## Document History
### 1. Does the working group (WG) consensus represent the strong concurrence
of a few individuals, with others being silent, or did it reach broad agreement?
The document reached broad agreement within the working group. The document
originated from a thread in May-June 2024 titled "HTTP->HTTPS redirects bad for
API traffic?" which generated discussion from multiple participants including
Mike Bishop, Lucas Pardue, Ben Bucksch, Roberto Polli, and Martin Thomson
before being adopted as a working group document in November 2024.
Technical discussions during development were substantive and constructive,
with active participation from multiple contributors in GitHub issues including
Joachim Viide (author of the motivating blog post), Marius Kleidl (document
co-author), and others. Five GitHub issues tracked technical discussions, all
of which were resolved with consensus. Key contributors included both document
authors and external participants from companies implementing the
recommendations.
Working Group Last Call was conducted from September 27 to October 11, 2025,
with no objections raised. The WGLC concluded successfully on October 24, 2025,
with the chair confirming that all comments received had been addressed by the
authors. The document received positive engagement from prominent HTTP experts
throughout its development.
### 2. Was there controversy about particular points, or were there decisions
where the consensus was particularly rough?
The document had several substantive technical discussions that were ultimately
resolved with consensus:
**Client HTTPS requirements (GitHub Issue #7, September 2024-June 2025):**
Martin Thomson proposed that clients MUST use HTTPS exclusively, eliminating
the need for HSTS and upgrade mechanisms. After discussion, the working group
adopted a compromise requiring clients to implement and use HTTPS exclusively
"absent a deliberate indication that an insecure context is deliberate." This
balances security with practical testing scenarios while making the default
secure.
**HTTP Status Code selection (GitHub Issue #3, August 2024):** Extended
discussion among Mike Bishop, Rich Salz, Joachim Viide, and Marius Kleidl about
which status code to recommend (403, 421, or 426). The group reached consensus
on 403 (Forbidden) as it best represents "the server understood the request but
refuses to fulfill it" for reasons unrelated to credential validity. The
discussion also led to important guidance that servers MUST NOT validate
credentials over insecure channels to avoid timing attacks and credential
enumeration.
**Signature-based authentication (GitHub Issue #8, October 2024-June 2025):**
Discussion about whether to revoke credentials when requests use
signature-based authentication (e.g., HMAC) where the secret isn't directly
transmitted. The resolution added text distinguishing between direct credential
transmission and derived values, allowing servers discretion not to revoke when
only signatures are exposed.
The HTTP Directorate review (July 26, 2025) by Mark Nottingham resulted in "On
the Right Track" with follow-up discussion from Tim Bray, Martin Thomson, Mark
Nottingham, and Roy T. Fielding on July 28-29, 2025. The Security Directorate
review (August 13-14, 2025) by Christian Huitema found "Has Nits" which were
addressed. The working group last call (September 27 - October 11, 2025)
concluded with no objections.
### 3. Has anyone threatened an appeal or otherwise indicated extreme
discontent? If so, please summarize the areas of conflict in separate email
messages to the responsible Area Director. (It should be in a separate email
because this questionnaire is publicly available.)
No. There have been no appeals or indications of extreme discontent throughout
the document's development.
### 4. For protocol documents, are there existing implementations of the
contents of the document? Have a significant number of potential implementers
indicated plans to implement? Are any existing implementations reported
somewhere, either in the document itself (as RFC 7942 recommends) or elsewhere
(where)?
This is a Best Current Practice document providing guidance rather than a
protocol specification. However, the recommendations build upon existing,
widely-implemented technologies (HSTS per RFC 6797, HTTPS DNS records per RFC
9460, Cookie Secure attribute per RFC 6265, Secret Token format per RFC 8959).
The document was motivated by observed real-world vulnerabilities, as
documented in the mentioned blog post that identified over two dozen websites
with the problematic HTTP-to-HTTPS redirect pattern for authenticated endpoints.
No specific implementation reports were submitted during the standardization
process, which is typical for BCP documents that provide operational guidance
rather than protocol specifications. The recommendations are intended to be
adopted by API providers as part of their security practices.
## Additional Reviews
### 5. Do the contents of this document closely interact with technologies in
other IETF working groups or external organizations, and would it therefore
benefit from their review? Have those reviews occurred? If yes, describe which
reviews took place.
This document interacts with several existing IETF specifications:
- HTTP-related work (HTTPBIS WG) - references RFC 9110 (HTTP Semantics)
- Security-related specifications (SEC area) - HSTS (RFC 6797), HTTPS DNS
records (RFC 9460) - Cookie specifications - RFC 6265 - Authentication tokens -
RFC 8959
Early reviews were requested and completed:
**HTTP Directorate Review (July 25-26, 2025):**
- Reviewer: Mark Nottingham
- Result: "On the Right Track"
- Follow-up discussion with Tim Bray, Martin Thomson, Mark Nottingham, and Roy
T. Fielding (July 28-29, 2025) - Issues addressed by authors
**Security Directorate Review (August 7-14, 2025):**
- Reviewer: Christian Huitema
- Result: "Has Nits"
- Authors responded on August 14, 2025, addressing the nits identified
Both reviews were positive and issues raised were resolved.
### 6. Describe how the document meets any required formal expert review
criteria, such as the MIB Doctor, YANG Doctor, media type, and URI type reviews.
No formal expert reviews are required for this document. This is a Best Current
Practice document that does not define MIBs, YANG modules, media types, or URI
schemes.
### 7. If the document contains a YANG module, has the final version of the
module been checked with any of the recommended validation tools for syntax and
formatting validation? If there are any resulting errors or warnings, what is
the justification for not fixing them at this time? Does the YANG module comply
with the Network Management Datastore Architecture (NMDA) as specified in RFC
8342?
Not applicable - this document does not contain a YANG module.
### 8. Describe reviews and automated checks performed to validate sections of
the final version of the document written in a formal language, such as XML
code, BNF rules, MIB definitions, CBOR's CDDL, etc.
Not applicable - this document does not contain formal language specifications.
## Document Shepherd Checks
### 9. Based on the shepherd's review of the document, is it their opinion that
this document is needed, clearly written, complete, correctly designed, and
ready to be handed off to the responsible Area Director?
Yes. This document addresses a significant and under-appreciated security
vulnerability in HTTP API deployments. The automatic HTTP-to-HTTPS redirect
pattern, while appropriate for web browsers, creates a credential exposure risk
for authenticated API traffic. The document is clearly written with
well-structured recommendations separated into server and client sections. The
recommendations are practical and build upon existing, proven technologies.
The document has received positive reviews from both the HTTP Directorate and
Security Directorate, with all identified issues resolved. Working group
consensus was strong, with no objections during the two-week last call period.
The document is ready for Area Director review and progression to IESG.
### 10. Several IETF Areas have assembled lists of common issues that their
reviewers encounter. For which areas have such issues been identified and
addressed? For which does this still need to happen in subsequent reviews?
The document has been reviewed for common issues in the relevant areas:
**WIT Area:** The HTTP Directorate review by Mark Nottingham (July 26, 2025)
found the document "On the Right Track," indicating that HTTP-specific
considerations were properly addressed.
**Security Area:** The Security Directorate review by Christian Huitema (August
14, 2025) identified minor nits which were addressed by the authors.
No additional area-specific reviews are anticipated to be needed.
### 11. What type of RFC publication is being requested on the IETF stream
(Best Current Practice, Proposed Standard, Internet Standard, Informational,
Experimental or Historic)? Why is this the proper type of RFC? Do all
Datatracker state attributes correctly reflect this intent?
**Requested Publication Type:** Best Current Practice (BCP)
**Justification:** This document provides operational and deployment guidance
for HTTP APIs rather than defining a new protocol or mechanism. It documents
best practices for protecting credentials in HTTP API deployments by
recommending how to properly use existing protocols (HSTS, HTTPS DNS records,
Cookie Secure attribute, etc.). BCP is the appropriate document type for this
guidance-focused content.
The Datatracker correctly reflects the BCP intent in the document metadata
(category: bcp).
### 12. Have reasonable efforts been made to remind all authors of the
intellectual property rights (IPR) disclosure obligations described in BCP 79?
To the best of your knowledge, have all required disclosures been filed? If
not, explain why. If yes, summarize any relevant discussion, including links to
publicly-available messages when applicable.
Yes. The Working Group Last Call announcement (September 27, 2025) included the
standard IPR reminder:
"Authors, and WG participants in general, are reminded again of the
Intellectual Property Rights (IPR) disclosure obligations described in BCP 79.
Appropriate IPR disclosures required for full conformance with the provisions
of BCP 78 and BCP 79 must be filed, if you are aware of any."
A search of the IPR disclosure database shows no disclosures related to this
document. All three authors have been active participants in IETF work and are
familiar with IPR disclosure obligations.
### 13. Has each author, editor, and contributor shown their willingness to be
listed as such? If the total number of authors and editors on the front page is
greater than five, please provide a justification.
The document lists three authors:
- Rich Salz (Akamai Technologies)
- Mike Bishop (Akamai Technologies)
- Marius Kleidl (Transloadit)
All three authors have been active throughout the document's development. Rich
Salz initiated the work and has been primary contact. Mike Bishop participated
in the early discussions (May-September 2024) that led to document adoption.
All authors participated in responding to directorate reviews in July-August
2025. The number of authors (three) is appropriate and does not require
additional justification.
### 14. Document any remaining I-D nits in this document. Simply running the
idnits tool is not enough; please review the "Content Guidelines" on
authors.ietf.org. (Also note that the current idnits tool generates some
incorrect warnings; a rewrite is underway.)
No issues were identified by running the idnits tool.
**Content Guidelines Review:**
The document has been reviewed against the IETF Content Guidelines
(https://authors.ietf.org/en/content-guidelines-overview):
**Required Content - All Present and Compliant:**
- **Abstract**: Present, concise (~60 words), stands alone, explains the
problem (HTTP-to-HTTPS redirects for authenticated APIs), does not contain
citations - **Status of This Memo**: Auto-generated by RFCXML tooling (v: 3) -
**Copyright Notice**: Auto-generated via ipr attribute - **Introduction**:
Present, explains motivation (credential exposure via redirects), references
the motivating blog post, describes applicability to authenticated HTTP APIs -
**Security Considerations**: Substantial section appropriate for a
security-focused BCP, addresses DoS risks from credential revocation
recommendation - **IANA Considerations**: Present, correctly states "This
document has no IANA actions" - **References**: Properly split into normative
and informative sections, all references are stable and appropriate -
**Authors' Addresses**: Three authors listed (within the 5-author limit),
includes affiliations and email addresses
**Language and Style - Compliant:**
- **BCP 14 Keywords**: Properly used with boilerplate reference, appropriate
use of MUST, SHOULD, MAY with clear justifications - **Abbreviations**:
Standard abbreviations used correctly (HTTP, HTTPS, HSTS, API, TLS, MAC, VPN,
DNS) - **Not claiming RFC status**: Document correctly refers to itself as a
document - **Inclusive language**: No problematic terminology identified
**Minor Observations (Not Requiring Changes):**
- The title "API Keys and Privacy" emphasizes "keys" but the document covers
all authenticated APIs. The abstract and introduction make the broader scope
clear. - Privacy Considerations section is not present as recommended by RFC
6973, but the document's focus is on credential security (preventing exposure)
rather than personal data privacy, so the current structure is appropriate.
The document conforms to all required IETF content guidelines.
### 15. Should any informative references be normative or vice-versa? See the
IESG Statement on Normative and Informative References.
The document's reference classification appears appropriate:
**Normative references:**
- RFC 6265 (Cookies) - normatively referenced for the Secure attribute
- RFC 6797 (HSTS) - normatively referenced for server and client requirements
- RFC 9110 (HTTP Semantics) - normatively referenced for status code definitions
- RFC 9460 (HTTPS DNS records) - normatively referenced for server and client
requirements
**Informative references:**
- RFC 8959 (Secret Token) - informatively referenced as an example mechanism
- Blog post - informatively referenced as motivation for the work
All classifications are appropriate. The normative references are required for
implementation of the recommendations, while the informative references provide
context or examples.
### 16. List any normative references that are not freely available to anyone.
Did the community have sufficient access to review any such normative
references?
All normative references are freely available RFCs published by the IETF.
### 17. Are there any normative downward references (see RFC 3967 and BCP 97)
that are not already listed in the DOWNREF registry? If so, list them.
There are no downward references in this document.
### 18. Are there normative references to documents that are not ready to be
submitted to the IESG for publication or are otherwise in an unclear state? If
so, what is the plan for their completion?
No. All normative references are published RFCs.
### 19. Will publication of this document change the status of any existing
RFCs? If so, does the Datatracker metadata correctly reflect this and are those
RFCs listed on the title page, in the abstract, and discussed in the
introduction? If not, explain why and point to the part of the document where
the relationship of this document to these other RFCs is discussed.
No. This document does not change the status of any existing RFCs. It provides
best practice guidance that builds upon and references existing specifications.
### 20. Describe the document shepherd's review of the IANA considerations
section, especially with regard to its consistency with the body of the
document. Confirm that all aspects of the document requiring IANA assignments
are associated with the appropriate reservations in IANA registries. Confirm
that any referenced IANA registries have been clearly identified. Confirm that
each newly created IANA registry specifies its initial contents, allocations
procedures, and a reasonable name (see RFC 8126).
The IANA Considerations section correctly states: "This document has no IANA
actions."
This is appropriate. The document does not define any new protocol elements,
status codes, headers, or other items that would require IANA registration. It
provides guidance on using existing, already-registered protocol elements.
### 21. List any new IANA registries that require Designated Expert Review for
future allocations. Are the instructions to the Designated Expert clear? Please
include suggestions of designated experts, if appropriate.
Not applicable - this document does not create any new IANA registries.