Protecting Credentials with HTTP APIs
draft-ietf-httpapi-privacy-06

[Ballot comment]
Thanks to the authors for addressing my DISCUSS. However, I am leaving my comments in place as not all of them seem to have been addressed.

Section 1, paragraph 4
>    This document describes actions API servers and clients should take
>    in order to safeguard credentials.  These recommendations are not
>    directed at resources where no authentication is used.

The HTTPDIR reviewer (thanks, Mark Nottingham) raised this concern,
and it does not appear to have been addressed in -04.
RFC 7258 establishes an IETF-wide consensus that passive monitoring
is an attack, and that all protocols should provide appropriate
confidentiality, regardless of whether authentication is present.
The current framing implicitly suggests that unencrypted HTTP is
acceptable for unauthenticated API traffic, which sits in tension
with RFC 7278's mandate.

A single added sentence acknowledging RFC 7258's broader scope —
while making clear that this document's specific recommendations
target authenticated APIs — would close the gap. For example:
"Although this document focuses on authenticated API endpoints,
operators should be aware that RFC 7258 establishes broader
reasons to use HTTPS regardless of whether credentials are transmitted."

Section 2.4, paragraph 1
>    HTTP status code 403 (Forbidden) indicates that "the server
>    understood the request but refuses to fulfill it" [HTTP].  While this
>    is generally understood to mean that "the server considers [the
>    credentials] insufficient to grant access," it also states that "a
>    request might be forbidden for reasons unrelated to the credentials."
>    HTTP API servers SHOULD return status code 403 to all requests
>    received over an insecure channel, regardless of the validity of the
>    presented credentials.

The document says servers SHOULD return 403 to *all* requests received
over an insecure channel, "regardless of the validity of the presented
credentials." But what about a request with no credentials at all
arriving over HTTP? Returning 403 to such a request discloses:

(a) the resource exists, and
(b) authentication is required.

An attacker scanning for credential-bearing endpoints could use this
to enumerate the API surface area. The alternative (e.g., closing the
connection without a response, or returning 400) might be preferable
for requests with no credentials. This is worth a sentence clarifying
the intended behavior.

Section 2.4.1, paragraph 0
>    When a request is received over an unencrypted channel, the presented
>    credential is potentially compromised.  HTTP API servers SHOULD
>    revoke such credentials immediately.  When the credential is next
>    used over a secure channel, the server MAY return an error that
>    indicates why the credential was revoked.

This paragraph recommends that servers SHOULD immediately revoke credentials
received over an insecure channel. Section 4 correctly identifies a DoS risk:
an attacker could deliberately present guessed credentials over HTTP to
trigger revocation of valid ones. The recommended mitigation is connection
rate-limiting, as the authors have already noted.

However, the document does not address the mirror problem: a legitimate but
misconfigured API client that routinely sends credentials over HTTP (e.g.,
because of a deployment error) would have its credentials repeatedly revoked,
disrupting service before the operator even notices the misconfiguration.
This is particularly relevant given the document's stated motivation —
that such misconfigurations are common and often go unnoticed.

A note acknowledging this trade-off (and suggesting, e.g., a notification
mechanism or grace period rather than immediate revocation in such cases)
would make the guidance more operationally realistic.

Section 3.2, paragraph 1
>    Clients MUST NOT send any header field that contains a secret token
>    over an insecure channel.  Such header fields include Authorization
>    and Proxy-Authorization and are described in Sections 11.6.2 and
>    11.7.2 of [RFC9110], respectively.

RFC9110 appears twice in the Normative References section under two
different labels. [HTTP] and [RFC9110]. Can this be reduced to one
reference, preferably [RFC9110], to be consistent with all other
references that use [RFCXXXX] instead of names?

Section 3.3, paragraph 0
>    When authentication is used, clients SHOULD require an explicit
>    indication from the user or caller that an insecure context is
>    expected which is distinct from the provided URI.  Depending on the
>    interface, this might be a UI preference or an API flag.

The phrase "distinct from the provided URI" is opaque. Reading it
with the examples ("a UI preference or an API flag"), the apparent
intent is that the indication of an allowed insecure context must
not be derived solely from the scheme of the URI
(i.e., using http:// is not itself a sufficient indication —
something separate must also be set). If so, that should be stated
directly. As written, a reader might interpret "distinct from the URI"
as something else entirely. How about saying - "which is distinct
from the provided URI, e.g., an UI preference or an API flag."?

Found terminology that should be reviewed for inclusivity; see
https://www.rfc-editor.org/part2/#inclusive_language for background and more
guidance:

* Term "his"; alternatives might be "they", "them", "their"

-------------------------------------------------------------------------------
NIT
-------------------------------------------------------------------------------

All comments below are about very minor potential issues that you may choose to
address in some way - or ignore - as you see fit. Some were flagged by
automated tools (via https://github.com/larseggert/ietf-reviewtool), so there
will likely be some false positives. There is no need to let me know what you
did with these suggestions.

"RFC9110", paragraph 1
> 1 creates the potential for a denial of service attack where an attacker gues
>                              ^^^^^^^^^^^^^^^^^
It appears that hyphens are missing.

[Ballot comment]
Thanks to Barry Leiba for the ARTART review.

I found the document to be very clear and to provide helpful guidance. There is; however, one sentence that was challenging for me to understand because I was not parsing it as I believe the authors intended.

- Section 3.3: When authentication is used, clients SHOULD require an explicit indication from the user or caller that an insecure context is expected which is distinct from the provided URI.

I did not understand what was meant by "an insecure context is expected which is distinct from the provided URI."

Thanks to the helpful shepherd writeup from Darrel Miller, I became aware of the following GitHub issue and resolution.

- "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.

I believe the following rewording aligns with the original intent, and it certainly helps me understand what is meant.

- Section 3.3: When authentication is used, clients SHOULD require an explicit indication, which is distinct from the provided URI, from the user or caller that an insecure context is expected.

[Ballot comment]
Thank you to Ron Evens for the GENART review.

** idnits:
  -- Duplicate reference: RFC9110, mentioned in 'RFC9110', was also mentioned
    in 'HTTP'.

** Section 1.
  Some have wondered if this document is really necessary.  After all,
  we have been telling people not to send passwords and such in the
  clear for decades.

-- Consider less colloquial language. 

-- Who are these “people”? Who is the “we” and where have “we” been “telling people”?

** Section 1.  Editorial.
  Regrettably, this lesson seems to be largely
  forgotten by those developing Web-based APIs.

Respectfully, this seems like a broad generalization, [BLOG] reference aside.  Is this text is needed to motivate the work?

** Editorial.  Consider if these idioms are approachable.
-- Abstract, “This document discusses the pitfalls …”
-- Section 2.1, “Neither mechanism is foolproof.”

** Other Editorial.  Other ADs have already mentioned that this document doesn’t seem strongly related to privacy despite it being in the title.

[Ballot comment]
Thanks to the authors and the WG for their work on this document.

Please find below some comments/suggestions to help improve the document.

1) I feel that the phrase "can be an anti-pattern for authenticated HTTP API traffic" might not be clear enough to (some or many?) readers. Perhaps a bit more prose or explanation would be helpful. Essentially what is being said is that following the same pattern for APIs (as is done for browsers) is not the best idea, even if it seems so on the first look, and has pitfalls and issues such as inadvertent disclosure of secure credentials ... < please rephrase in a more appropriate manner >

2) The title includes "Privacy", but since this is about credentials, should it also not include Security in the title?

3) There are duplicate references to RFC9110 - once as "HTTP" and then again as "RFC9110"

[Ballot comment]
Thanks to all the reviewers (Christian, Roni, Barry, Mark); the draft is well written and gives (more?) guidance on an important topic.

I think the other ADs and reviewers have covered any comments that I would provide at this point.

[Ballot comment]
Thanks to Christian Huitema for their secdir review.

I do appreciate the goal of this BCP, and I hope my suggestions might help convey the information more clearly.  My comments are not blocking, and my goal is to make the specification more easily understood.

General:  I do agree with Christian that this draft 'buries the lede' (https://www.merriam-webster.com/wordplay/bury-the-lede-versus-lead). If the goal of the BCP is to inform the community about the risks and vulnerabilities of credential exposure via unprotected web resources, then it should be stated plainly and directly.   

Abstract, sentence 1:  I'm not sure I understand what this means.  Is it the goal to redirect an HTTP request to an HTTPS port/server?  It does not read that way.  Terms like 'anti-pattern' are not used enough for clear understanding. 

Introduction:  Clearly para 3 and 4 get to the heart of the discussion.  I recommend moving that up to the start of the Introduction.

Section 2.1, sentence 1:  I had to read this sentence 4-5 times to understand the point.  How about, 'To inform clients that unencrypted requests to a server are never appropriate, there are various mechanisms available.'  (vice the current sentence which makes it look like the 'various mechanisms' are 'never appropriate')

Section 4, sentence 1:  I'm sure it is clear to nearly everyone what this means, but I might suggest a reword to something like, 'This entire document is about how to keep user credentials secure by controlling HTTP API interactions.'  (I'm sure you can do better than my suggestion)

[Ballot discuss]
Thank you to the authors for working on this short, real and well-motivated doucment that is practical and well-structured. These are but one DISCUSS, which should easy to address, and a few comments that I believe would go some ways to make it better.

Paragraph 1
>                          API Keys and Privacy

The title "API Keys and Privacy" is imprecise on both nouns:

The document covers all credential types — Bearer tokens, Cookies, API keys,
signature-based MAC credentials — not just API keys.

Section 4 states, "This entire document is about security of HTTP API
interactions", not privacy in the RFC 6973 sense. There is no Privacy
Considerations section (the shepherd correctly notes this is acceptable
given the scope), but then the title's use of "Privacy" is misleading.

Given that Barry Leiba and Roni Even found no issue with the title,
this is likely a matter of WG taste. However, a title like
"API Credential Security" or "Protecting Credentials in HTTP APIs"
would be more accurate.

[Ballot comment]
Section 1, paragraph 4
>    This document describes actions API servers and clients should take
>    in order to safeguard credentials.  These recommendations are not
>    directed at resources where no authentication is used.

The HTTPDIR reviewer (thanks, Mark Nottingham) raised this concern,
and it does not appear to have been addressed in -04.
RFC 7258 establishes an IETF-wide consensus that passive monitoring
is an attack, and that all protocols should provide appropriate
confidentiality, regardless of whether authentication is present.
The current framing implicitly suggests that unencrypted HTTP is
acceptable for unauthenticated API traffic, which sits in tension
with RFC 7278's mandate.

A single added sentence acknowledging RFC 7258's broader scope —
while making clear that this document's specific recommendations
target authenticated APIs — would close the gap. For example:
"Although this document focuses on authenticated API endpoints,
operators should be aware that RFC 7258 establishes broader
reasons to use HTTPS regardless of whether credentials are transmitted."

Section 2.4, paragraph 1
>    HTTP status code 403 (Forbidden) indicates that "the server
>    understood the request but refuses to fulfill it" [HTTP].  While this
>    is generally understood to mean that "the server considers [the
>    credentials] insufficient to grant access," it also states that "a
>    request might be forbidden for reasons unrelated to the credentials."
>    HTTP API servers SHOULD return status code 403 to all requests
>    received over an insecure channel, regardless of the validity of the
>    presented credentials.

The document says servers SHOULD return 403 to *all* requests received
over an insecure channel, "regardless of the validity of the presented
credentials." But what about a request with no credentials at all
arriving over HTTP? Returning 403 to such a request discloses:

(a) the resource exists, and
(b) authentication is required.

An attacker scanning for credential-bearing endpoints could use this
to enumerate the API surface area. The alternative (e.g., closing the
connection without a response, or returning 400) might be preferable
for requests with no credentials. This is worth a sentence clarifying
the intended behavior.

Section 2.4.1, paragraph 0
>    When a request is received over an unencrypted channel, the presented
>    credential is potentially compromised.  HTTP API servers SHOULD
>    revoke such credentials immediately.  When the credential is next
>    used over a secure channel, the server MAY return an error that
>    indicates why the credential was revoked.

This paragraph recommends that servers SHOULD immediately revoke credentials
received over an insecure channel. Section 4 correctly identifies a DoS risk:
an attacker could deliberately present guessed credentials over HTTP to
trigger revocation of valid ones. The recommended mitigation is connection
rate-limiting, as the authors have already noted.

However, the document does not address the mirror problem: a legitimate but
misconfigured API client that routinely sends credentials over HTTP (e.g.,
because of a deployment error) would have its credentials repeatedly revoked,
disrupting service before the operator even notices the misconfiguration.
This is particularly relevant given the document's stated motivation —
that such misconfigurations are common and often go unnoticed.

A note acknowledging this trade-off (and suggesting, e.g., a notification
mechanism or grace period rather than immediate revocation in such cases)
would make the guidance more operationally realistic.

Section 3.2, paragraph 1
>    Clients MUST NOT send any header field that contains a secret token
>    over an insecure channel.  Such header fields include Authorization
>    and Proxy-Authorization and are described in Sections 11.6.2 and
>    11.7.2 of [RFC9110], respectively.

RFC9110 appears twice in the Normative References section under two
different labels. [HTTP] and [RFC9110]. Can this be reduced to one
reference, preferably [RFC9110], to be consistent with all other
references that use [RFCXXXX] instead of names?

Section 3.3, paragraph 0
>    When authentication is used, clients SHOULD require an explicit
>    indication from the user or caller that an insecure context is
>    expected which is distinct from the provided URI.  Depending on the
>    interface, this might be a UI preference or an API flag.

The phrase "distinct from the provided URI" is opaque. Reading it
with the examples ("a UI preference or an API flag"), the apparent
intent is that the indication of an allowed insecure context must
not be derived solely from the scheme of the URI
(i.e., using http:// is not itself a sufficient indication —
something separate must also be set). If so, that should be stated
directly. As written, a reader might interpret "distinct from the URI"
as something else entirely. How about saying - "which is distinct
from the provided URI, e.g., an UI preference or an API flag."?

Found terminology that should be reviewed for inclusivity; see
https://www.rfc-editor.org/part2/#inclusive_language for background and more
guidance:

* Term "his"; alternatives might be "they", "them", "their"

-------------------------------------------------------------------------------
NIT
-------------------------------------------------------------------------------

All comments below are about very minor potential issues that you may choose to
address in some way - or ignore - as you see fit. Some were flagged by
automated tools (via https://github.com/larseggert/ietf-reviewtool), so there
will likely be some false positives. There is no need to let me know what you
did with these suggestions.

"RFC9110", paragraph 1
> 1 creates the potential for a denial of service attack where an attacker gues
>                              ^^^^^^^^^^^^^^^^^
It appears that hyphens are missing.

[Ballot comment]
Hi Rich, Mike, and Marius,

Thank you for the effort put into this operational document :-)

Please find some comments below:

# Lack of references when some concepts are first introduced

This includes Bearer token (Maybe cite rfc6750), HTTPS, and other similar in in the introduction in particular. Please consider adding some pointers there.

# Do we really need this text in the final RFC?

CURRENT:
  Some have wondered if this document is really necessary.  After all,
  we have been telling people not to send passwords and such in the
  clear for decades.  Regrettably, this lesson seems to be largely
  forgotten by those developing Web-based APIs.  The blog post that
  motivated this document, [BLOG], did a spot-check in May, 2024, and
  found over two dozen websites that were vulnerable to the issues
  listed here.

I think this text (and specifically  the first sentence) are not appropriate in a document that is stamped with IETF consensus.

# Mixing mechanism vs. actual use

CURRENT:
  Various mechanisms exist to inform clients that unencrypted requests
  to a server are never appropriate:

I’m afraid that we are mixing the mechanism vs it use. The statement above is true if and only if such RRs are published at the first place.

# How the developer will notice it?

CURRENT:
  If an API request succeeds despite having an unencrypted endpoint
  configured, the developer or user is less likely to notice the
  misconfiguration. 

Maybe I’m not visualizing the role of developer vs user.

# Servers vs. Operators

CURRENT:
  HTTP API servers MAY induce such an early failure by not accepting
  unencrypted connections, e.g. on port 80.  This makes it impossible
  for a client to send a credential over an insecure channel to the
  authentic server, as no such channel can be opened.  HTTP API servers
  MAY alternatively restrict connections on port 80 to network sources
  which are more trusted, such as a VPN or virtual network interface.

This should not be random decisions of servers, but local policies. I’m not sure who is the consumer of the above reco.

# I’m having troubles to separate the main guidance vs. examples to illustrate it in the following:

CURRENT:
  Whenever possible, credentials should include an indicator to clients
  that the credential is restricted to secure contexts.  For example,
  Cookie-based authentication SHOULD include the Secure attribute
  described in Section 4.1.2.5 of [RFC6265]. 

The first sentence should use normative language while the one with the example shouldn’t.

# Operators?

CURRENT:
  Some deployments might not find it feasible to completely block
  unencrypted connections, whether because the hostname is shared with
  unauthenticated endpoints or for infrastructure reasons. 

A deployment can not auto-assess what is feasible. I think this is better formulated by addressing to operators or those who deploy or exapose an API, or similar.

# I guess the following should be policy-based

OLD:
  HTTP API servers SHOULD return status code 403 to all requests
  received over an insecure channel, regardless of the validity of the
  presented credentials.

NEW:
  HTTP API servers SHOULD return status code 403 to all requests
  received over an insecure channel, regardless of the validity of the
  presented credentials, unless configured otherwise.

# Query is inherited by support of 9460

CURRENT:
  Clients SHOULD support and query for HTTPS records [RFC9460] when
  establishing a connection. 

A client that support RFC9460 will inherit the following from 9460:

  Prior to making an
  "http" scheme request, the client SHOULD perform a lookup to
  determine if any HTTPS RRs exist for that origin.

I would simply say:

NEW:
  Clients SHOULD support HTTPS records [RFC9460]. 

# Caller vs. user

CURRENT:
  When authentication is used, clients SHOULD require an explicit
  indication from the user or caller that an insecure context is

What is the difference between the two? If none, I would keep “user” only. If these are distinct, then please clarify that in the text. Thanks.

Cheers,
Med

[Ballot comment]
Thank you for the clean and brief write-up.

When going through the text i found it amusing that the page "Your API Shouldn't Redirect HTTP to HTTPS" (https://jviide.iki.fi/http-redirects) is actually redirected to https when one tries to access the content using legacy request to "http://jviide.iki.fi/http-redirects"

Thanks for documenting this BCP

[Ballot comment]
Thanks for the work done in this short and sweet document. Just one comment: who is the "we" in `After all, we have been telling people not to send passwords` ? The authors ? The WG ? The IETF ? Please avoid any ambiguities.

The following Last Call announcement was sent out (ends 2026-03-12):

From: The IESG
To: IETF-Announce
CC: darrel@tavis.ca, draft-ietf-httpapi-privacy@ietf.org, gorry@erg.abdn.ac.uk, httpapi-chairs@ietf.org, httpapi@ietf.org
Reply-To: last-call@ietf.org
Sender:
Subject: Last Call:  (API Keys and Privacy) to Best Current Practice


The IESG has received a request from the Building Blocks for HTTP APIs WG
(httpapi) to consider the following document: - 'API Keys and Privacy'
  as Best Current Practice

The IESG plans to make a decision in the next few weeks, and solicits final
comments on this action. Please send substantive comments to the
last-call@ietf.org mailing lists by 2026-03-12. Exceptionally, comments may
be sent to iesg@ietf.org instead. In either case, please retain the beginning
of the Subject line to allow automated sorting.

Abstract


  Redirecting HTTP requests to HTTPS, a common pattern for human-facing
  web resources, can be an anti-pattern for authenticated HTTP API
  traffic.  This document discusses the pitfalls and makes deployment
  recommendations for authenticated HTTP APIs.  It does not specify a
  protocol.




The file can be obtained via
https://datatracker.ietf.org/doc/draft-ietf-httpapi-privacy/



No IPR declarations have been submitted directly on this I-D.

# 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.

# 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.

Please review the document and send your comments to the HTTPAPI WG mailing list
(https://www.ietf.org/mailman/listinfo/httpapi).

When providing feedback, please indicate whether you believe this document is
ready for publication, or if you have concerns that need to be addressed.

**Note:** There is an open issue from the HTTPDIR review (https://datatracker.ietf.org/doc/review-ietf-httpapi-privacy-02-httpdir-early-nottingham-2025-07-26/) that calls for "a stronger requirement for encryption in general". If you have
opinions on this issue, please include them in your review.

As a reminder, this is the time to confirm that the document is technically
sound, clear, and complete. Please also check for any IPR disclosures related
to this draft: https://datatracker.ietf.org/ipr/search/?submit=draft&id=draft-ietf-httpapi-privacy

Thank you for your reviews and contributions.