HTTP AAuth Headers
draft-hardt-aauth-headers-00
This document is an Internet-Draft (I-D).
Anyone may submit an I-D to the IETF.
This I-D is not endorsed by the IETF and has no formal standing in the
IETF standards process.
| Document | Type | Active Internet-Draft (individual) | |
|---|---|---|---|
| Author | Dick Hardt | ||
| Last updated | 2026-04-02 | ||
| RFC stream | (None) | ||
| Intended RFC status | (None) | ||
| Formats | |||
| Stream | Stream state | (No stream defined) | |
| Consensus boilerplate | Unknown | ||
| RFC Editor Note | (None) | ||
| IESG | IESG state | I-D Exists | |
| Telechat date | (None) | ||
| Responsible AD | (None) | ||
| Send notices to | (None) |
draft-hardt-aauth-headers-00
TBD D. Hardt
Internet-Draft Hellō
Intended status: Standards Track 2 April 2026
Expires: 4 October 2026
HTTP AAuth Headers
draft-hardt-aauth-headers-00
Abstract
This document defines two HTTP response headers — AAuth-Requirement
and AAuth-Error — and profiles HTTP Message Signatures ([RFC9421])
for request authentication, with keying material conveyed via the
Signature-Key header ([I-D.hardt-httpbis-signature-key]). A server
uses AAuth-Requirement to require pseudonymous or verified agent
identity, to request user interaction, or to signal that approval is
pending. AAuth-Error conveys structured error information. Both
headers use extensible registries for their values.
Discussion Venues
_Note: This section is to be removed before publishing as an RFC._
This document is part of the AAuth specification family. Source for
this draft and an issue tracker can be found at
https://github.com/dickhardt/AAuth (https://github.com/dickhardt/
AAuth).
Status of This Memo
This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet-
Drafts is at https://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress."
This Internet-Draft will expire on 4 October 2026.
Hardt Expires 4 October 2026 [Page 1]
Internet-Draft AAuth-Headers April 2026
Copyright Notice
Copyright (c) 2026 IETF Trust and the persons identified as the
document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents (https://trustee.ietf.org/
license-info) in effect on the date of publication of this document.
Please review these documents carefully, as they describe your rights
and restrictions with respect to this document. Code Components
extracted from this document must include Revised BSD License text as
described in Section 4.e of the Trust Legal Provisions and are
provided without warranty as described in the Revised BSD License.
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3
2. Conventions and Definitions . . . . . . . . . . . . . . . . . 3
3. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 4
4. AAuth-Requirement HTTP Response Header . . . . . . . . . . . 4
4.1. Header Structure . . . . . . . . . . . . . . . . . . . . 4
4.2. Requirement Levels . . . . . . . . . . . . . . . . . . . 5
4.3. Pseudonym Required . . . . . . . . . . . . . . . . . . . 5
4.4. Identity Required . . . . . . . . . . . . . . . . . . . . 6
4.5. Interaction Required . . . . . . . . . . . . . . . . . . 7
4.6. Approval Pending . . . . . . . . . . . . . . . . . . . . 9
5. HTTP Message Signatures Profile . . . . . . . . . . . . . . . 9
5.1. Signature Algorithms . . . . . . . . . . . . . . . . . . 9
5.2. Keying Material . . . . . . . . . . . . . . . . . . . . . 9
5.3. Signing (Agent) . . . . . . . . . . . . . . . . . . . . . 10
5.3.1. Covered Components . . . . . . . . . . . . . . . . . 10
5.3.2. Signature Parameters . . . . . . . . . . . . . . . . 10
5.4. Verification (Server) . . . . . . . . . . . . . . . . . . 10
6. AAuth-Error HTTP Response Header . . . . . . . . . . . . . . 11
6.1. Header Structure . . . . . . . . . . . . . . . . . . . . 11
6.2. Error Codes . . . . . . . . . . . . . . . . . . . . . . . 12
6.2.1. invalid_request . . . . . . . . . . . . . . . . . . . 12
6.2.2. invalid_input . . . . . . . . . . . . . . . . . . . . 12
6.2.3. invalid_signature . . . . . . . . . . . . . . . . . . 12
6.2.4. unsupported_algorithm . . . . . . . . . . . . . . . . 12
6.2.5. invalid_key . . . . . . . . . . . . . . . . . . . . . 12
6.2.6. unknown_key . . . . . . . . . . . . . . . . . . . . . 13
6.2.7. invalid_jwt . . . . . . . . . . . . . . . . . . . . . 13
6.2.8. expired_jwt . . . . . . . . . . . . . . . . . . . . . 13
6.3. Access Denied . . . . . . . . . . . . . . . . . . . . . . 13
7. Privacy Considerations . . . . . . . . . . . . . . . . . . . 13
7.1. Key Thumbprint Tracking . . . . . . . . . . . . . . . . . 13
7.2. Agent Identity Disclosure . . . . . . . . . . . . . . . . 14
Hardt Expires 4 October 2026 [Page 2]
Internet-Draft AAuth-Headers April 2026
7.3. JWKS Fetch Side Channel . . . . . . . . . . . . . . . . . 14
8. Security Considerations . . . . . . . . . . . . . . . . . . . 14
8.1. HTTP Message Signature Security . . . . . . . . . . . . . 14
8.2. Replay Protection . . . . . . . . . . . . . . . . . . . . 14
8.3. JWKS Caching . . . . . . . . . . . . . . . . . . . . . . 15
9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 15
9.1. HTTP Header Field Registration . . . . . . . . . . . . . 15
9.2. AAuth Requirement Level Registry . . . . . . . . . . . . 15
9.3. AAuth Error Code Registry . . . . . . . . . . . . . . . . 16
10. Design Rationale . . . . . . . . . . . . . . . . . . . . . . 17
10.1. Why Not Extend WWW-Authenticate? . . . . . . . . . . . . 17
11. Implementation Status . . . . . . . . . . . . . . . . . . . . 17
12. Document History . . . . . . . . . . . . . . . . . . . . . . 18
13. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 18
14. References . . . . . . . . . . . . . . . . . . . . . . . . . 18
14.1. Normative References . . . . . . . . . . . . . . . . . . 18
14.2. Informative References . . . . . . . . . . . . . . . . . 19
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 20
1. Introduction
Modern distributed systems need a standard way for servers to
communicate requirements to agents and for agents to present
cryptographic identity. The existing HTTP WWW-Authenticate header
([RFC9110], Section 11.6.1) is limited to a fixed set of
authentication schemes, cannot express progressive requirements, and
cannot appear in 202 Accepted responses. The AAuth-Requirement
header provides an extensible mechanism for progressive requirements
— from pseudonymous access and verified identity to user interaction
and deferred approval.
This specification defines:
* The AAuth-Requirement HTTP response header with an extensible
requirement level registry
* Four requirement levels: pseudonym, identity, interaction, and
approval
* A profile of HTTP Message Signatures ([RFC9421]) for request
authentication, specifying required covered components, signature
parameters, and keying material via the Signature-Key header
([I-D.hardt-httpbis-signature-key])
* The AAuth-Error HTTP response header with an extensible error code
registry
2. Conventions and Definitions
{::boilerplate bcp14-tagged}
Hardt Expires 4 October 2026 [Page 3]
Internet-Draft AAuth-Headers April 2026
All HTTP requests and responses in AAuth MUST use HTTPS (HTTP over
TLS ([RFC8446])). Any reference to "HTTP" in this document implies
HTTPS unless explicitly noted otherwise.
3. Terminology
* *Agent*: An HTTP client ([RFC9110], Section 3.5) that signs its
requests. In AAuth, agents have cryptographic identity.
* *Server*: An HTTP origin server ([RFC9110], Section 3.6) that
communicates requirements via the AAuth-Requirement header.
4. AAuth-Requirement HTTP Response Header
Servers use the AAuth-Requirement response header to indicate
requirements to agents. The header MAY be sent with 401 Unauthorized
or 202 Accepted responses. A 401 response indicates that
authentication or authorization is required. A 202 response
indicates that the request is pending and additional action is
required — either user interaction (requirement=interaction) or
third-party approval (requirement=approval).
AAuth-Requirement and WWW-Authenticate are independent header fields;
a response MAY include both. A client that understands AAuth
processes AAuth-Requirement; a legacy client processes WWW-
Authenticate. Neither header's presence invalidates the other.
The header MAY also be sent with 402 Payment Required when a server
requires both authentication and payment. The AAuth-Requirement
conveys the authentication requirement; the payment requirement is
conveyed by a separate mechanism such as x402 [x402] or the
Micropayment Protocol (MPP) ([I-D.ryan-httpauth-payment]).
4.1. Header Structure
The AAuth-Requirement header field is a Dictionary ([RFC8941],
Section 3.2). It MUST contain the following member:
* requirement: A Token ([RFC8941], Section 3.3.4) indicating the
requirement level.
Additional members are defined per requirement level by the
specification that registers the level. Recipients MUST ignore
unknown members.
Example:
AAuth-Requirement: requirement=pseudonym
Hardt Expires 4 October 2026 [Page 4]
Internet-Draft AAuth-Headers April 2026
4.2. Requirement Levels
The requirement value is an extension point. This document defines
four levels:
+=============+=============+=======================================+
| Level | Status Code | Meaning |
+=============+=============+=======================================+
| pseudonym | 401 | Signed request proving |
| | | key possession |
+-------------+-------------+---------------------------------------+
| identity | 401 | Verified agent identity |
+-------------+-------------+---------------------------------------+
| interaction | 202 | User action required at |
| | | an interaction endpoint |
+-------------+-------------+---------------------------------------+
| approval | 202 | Approval pending, poll |
| | | for result |
+-------------+-------------+---------------------------------------+
Table 1
The AAuth Protocol specification (draft-hardt-aauth-protocol)
registers additional levels (e.g., auth-token).
4.3. Pseudonym Required
When a server requires a signed request:
HTTP/1.1 401 Unauthorized
AAuth-Requirement: requirement=pseudonym
The agent retries with an HTTP Message Signature using a pseudonymous
Signature-Key scheme ({{keying-material}}). The server can track the
agent by JWK Thumbprint ([RFC7638]) without knowing its identity.
Hardt Expires 4 October 2026 [Page 5]
Internet-Draft AAuth-Headers April 2026
Agent Server
| |
| unsigned request |
|---------------------------------------------->|
| |
| 401 Unauthorized |
| AAuth-Requirement: requirement=pseudonym |
|<----------------------------------------------|
| |
| HTTPSig request |
| (pseudonymous key) |
|---------------------------------------------->|
| | verify signature,
| | track by key
| | thumbprint
| |
| 200 OK |
|<----------------------------------------------|
| |
If the agent already knows the server requires pseudonymous access
(from a previous interaction or metadata), it MAY sign the initial
request directly without waiting for a 401 challenge.
*Use cases:* Rate limiting anonymous requests, tracking repeat
visitors by key thumbprint, spam prevention without requiring
verified identity, hardware-backed pseudonymous identity.
4.4. Identity Required
When a server requires verified agent identity:
HTTP/1.1 401 Unauthorized
AAuth-Requirement: requirement=identity
The agent retries with a signed request using an identity Signature-
Key scheme ({{keying-material}}).
Hardt Expires 4 October 2026 [Page 6]
Internet-Draft AAuth-Headers April 2026
Agent Server
| |
| HTTPSig request |
|---------------------------------------------->|
| |
| 401 Unauthorized |
| AAuth-Requirement: requirement=identity |
|<----------------------------------------------|
| |
| HTTPSig request |
| (verifiable identity) |
|---------------------------------------------->|
| | verify agent
| | identity,
| | apply policy
| |
| 200 OK |
|<----------------------------------------------|
| |
If the agent already knows the server requires agent identity, it MAY
present its identity on the initial request without waiting for a 401
challenge.
*Use cases:* API access policies based on known agents, webhook
signature verification, allowlisting trusted agents for elevated rate
limits.
4.5. Interaction Required
When a server requires user action — such as authentication, consent,
payment approval, or any decision requiring a human in the loop — it
returns a 202 Accepted response:
HTTP/1.1 202 Accepted
AAuth-Requirement: requirement=interaction; url="https://example.com/interact";
code="A1B2-C3D4"
Location: /pending/f7a3b9c
Retry-After: 0
The AAuth-Requirement header MUST include the following parameters:
* url (String): The interaction URL where the user completes the
required action. MUST use the https scheme and MUST NOT contain
query or fragment components.
* code (String): An interaction code that links the agent's pending
request to the user's session at the interaction URL.
Hardt Expires 4 October 2026 [Page 7]
Internet-Draft AAuth-Headers April 2026
The response MUST also include:
* Location: A URL the agent polls (with GET) for a terminal
response.
* Retry-After: Recommended polling interval in seconds.
The agent constructs a user-facing URL by appending the code as a
query parameter: {url}?code={code}. The agent then directs the user
to this URL using one of:
* *Browser redirect*: The agent opens the URL in the user's browser.
* *Display code*: The agent displays the url and code for the user
to enter manually. The agent MAY also render the constructed URL
as a QR code for the user to scan with their phone.
After directing the user, the agent polls the Location URL with GET
requests, respecting the Retry-After interval. A 202 response means
the request is still pending. A non-202 response is terminal — 200
indicates success, 403 indicates denial, and 408 indicates timeout.
Agent User Server
| | |
| 202 Accepted |
| AAuth-Requirement: |
| requirement=interaction; |
| url="..."; code="..." |
| Location: /pending/... |
|<---------------------------------------------------------|
| | |
| open {url}?code={code} | |
| (or display code / QR) | |
|--------------------------->| |
| | |
| | {url}?code={code} |
| |---------------------------->|
| | |
| | user completes action |
| |<----------------------------|
| | |
| GET /pending/... |
|--------------------------------------------------------->|
| | |
| 200 OK |
|<---------------------------------------------------------|
*Use cases:* User login, consent, payment confirmation, document
review, CAPTCHA, any workflow requiring human action.
Hardt Expires 4 October 2026 [Page 8]
Internet-Draft AAuth-Headers April 2026
4.6. Approval Pending
When a server is obtaining approval from another party without
requiring the agent to direct a user — for example, via push
notification, email, or administrator review:
HTTP/1.1 202 Accepted
AAuth-Requirement: requirement=approval
Location: /pending/f7a3b9c
Retry-After: 30
The response MUST include Location and Retry-After. The agent polls
the Location URL with GET requests until a terminal response is
received. No user action is required at the agent side. The same
terminal response codes apply as for interaction.
*Use cases:* Administrator approval, resource owner consent,
compliance review, direct user authorization via established
communication channel.
5. HTTP Message Signatures Profile
This section profiles HTTP Message Signatures ([RFC9421]) for use
with AAuth. Signing requirements (what the agent does) and
verification requirements (what the server does) are specified
separately.
5.1. Signature Algorithms
Agents and resources MUST support EdDSA using Ed25519 ([RFC8032]).
Agents and resources SHOULD support ECDSA using P-256 with
deterministic signatures ([RFC6979]). The alg parameter in the JWK
([RFC7517]) key representation identifies the algorithm. See the
IANA JSON Web Signature and Encryption Algorithms registry
([RFC7518], Section 7.1) for the full list of algorithm identifiers.
5.2. Keying Material
The signing key is conveyed in the Signature-Key header
([I-D.hardt-httpbis-signature-key]). The Signature-Key scheme
determines how the server obtains the public key:
* For pseudonym: the agent uses scheme=hwk (inline public key) or
scheme=jkt-jwt (delegation from a hardware-backed key).
* For identity: the agent uses scheme=jwks_uri (JWKS endpoint) or
scheme=jwt (JWT with public key in cnf claim).
Hardt Expires 4 October 2026 [Page 9]
Internet-Draft AAuth-Headers April 2026
See the Signature-Key specification
([I-D.hardt-httpbis-signature-key]) for scheme definitions, key
discovery, and verification procedures.
5.3. Signing (Agent)
The agent creates an HTTP Message Signature ([RFC9421]) on each
request, including the following headers:
* Signature-Key: Public key or key reference for signature
verification
* Signature-Input: Signature metadata including covered components
* Signature: The HTTP message signature
5.3.1. Covered Components
The signature MUST cover the following derived components and header
fields:
* @method: The HTTP request method ([RFC9421], Section 2.2.1)
* @authority: The target host ([RFC9421], Section 2.2.3)
* @path: The request path ([RFC9421], Section 2.2.6)
* signature-key: The Signature-Key header value
Servers MAY require additional covered components (e.g., content-
digest ([RFC9530]) for request body integrity). The agent learns
about additional requirements from server metadata or from an
invalid_input error response that includes required_input ({{error-
codes}}).
5.3.2. Signature Parameters
The Signature-Input header ([RFC9421], Section 4.1) MUST include the
following parameters:
* created: Signature creation timestamp as an Integer (Unix time).
The agent MUST set this to the current time.
5.4. Verification (Server)
When a server receives a signed request, it MUST perform the
following steps. Any failure MUST result in a 401 response with the
appropriate AAuth-Error header ({{error-codes}}).
1. Extract the Signature, Signature-Input, and Signature-Key
headers. If any are missing, return invalid_request.
Hardt Expires 4 October 2026 [Page 10]
Internet-Draft AAuth-Headers April 2026
2. Verify that the Signature-Input covers the required components
defined in {{covered-components}}. If the server requires
additional components, verify those are covered as well. If not,
return invalid_input with required_input.
3. Verify the created parameter is present and within 60 seconds of
the server's current time. Reject with invalid_signature if
outside this window. Servers and agents SHOULD synchronize their
clocks using NTP ([RFC5905]).
4. Determine the signature algorithm from the alg parameter in the
key. If the algorithm is not supported, return
unsupported_algorithm.
5. Obtain the public key from the Signature-Key header according to
the scheme, as specified in ([I-D.hardt-httpbis-signature-key]).
Return invalid_key if the key cannot be parsed, unknown_key if
the key is not found at the jwks_uri, invalid_jwt if a JWT scheme
fails verification, or expired_jwt if the JWT has expired.
6. Verify the HTTP Message Signature ([RFC9421]) using the obtained
public key and determined algorithm. Return invalid_signature if
verification fails.
6. AAuth-Error HTTP Response Header
When a server rejects a request that includes AAuth signature headers
(Signature, Signature-Input, and Signature-Key), the 401 response
MUST include the AAuth-Error header.
6.1. Header Structure
The AAuth-Error header field is a Dictionary ([RFC8941],
Section 3.2). It MUST contain the following member:
* error: A Token ([RFC8941], Section 3.3.4) indicating the error
code.
Additional members are defined per error code. Recipients MUST
ignore unknown members.
AAuth-Error: error=unsupported_algorithm,
supported_algorithms=("EdDSA" "ES256")
The response body is OPTIONAL and MAY contain a human-readable
description in any content type. The agent MUST NOT depend on the
response body for error handling — all machine-readable error
information is in the header.
Hardt Expires 4 October 2026 [Page 11]
Internet-Draft AAuth-Headers April 2026
6.2. Error Codes
6.2.1. invalid_request
The request is malformed or missing required information unrelated to
signature verification — such as missing query parameters or an
unsupported content type.
AAuth-Error: error=invalid_request
6.2.2. invalid_input
The Signature-Input is missing required covered components. The
response SHOULD include a required_input member listing the
components the server requires (see {{covered-components}} for the
base set):
AAuth-Error: error=invalid_input,
required_input=("@method" "@authority" "@path"
"signature-key" "content-digest")
6.2.3. invalid_signature
The HTTP Message Signature is missing, malformed, or cryptographic
verification failed. This includes missing Signature, Signature-
Input, or Signature-Key headers, an expired created timestamp, or a
signature that does not verify.
AAuth-Error: error=invalid_signature
6.2.4. unsupported_algorithm
The signing algorithm used by the agent is not supported by the
server. The response MUST include a supported_algorithms member:
AAuth-Error: error=unsupported_algorithm,
supported_algorithms=("EdDSA" "ES256")
6.2.5. invalid_key
The public key in Signature-Key could not be parsed, is expired, or
does not meet the server's trust requirements.
AAuth-Error: error=invalid_key
Hardt Expires 4 October 2026 [Page 12]
Internet-Draft AAuth-Headers April 2026
6.2.6. unknown_key
The public key from Signature-Key does not match any key at the
agent's jwks_uri (applicable when the agent uses scheme=jwks_uri for
verified identity; see {{keying-material}}). The server SHOULD re-
fetch the JWKS once before returning this error, to handle key
rotation.
AAuth-Error: error=unknown_key
6.2.7. invalid_jwt
The JWT in the Signature-Key header (when using scheme=jwt or
scheme=jkt-jwt) is malformed or its signature verification failed.
AAuth-Error: error=invalid_jwt
6.2.8. expired_jwt
The JWT in the Signature-Key header (when using scheme=jwt or
scheme=jkt-jwt) has expired (exp claim is in the past).
AAuth-Error: error=expired_jwt
6.3. Access Denied
When the server successfully verifies the agent's signature and
identity but denies access based on policy (e.g., the agent is not
authorized for this resource), the server returns 403 Forbidden.
This is not an AAuth error — the authentication succeeded but
authorization was denied. The response MUST NOT include an AAuth-
Requirement or AAuth-Error header.
7. Privacy Considerations
7.1. Key Thumbprint Tracking
When an agent uses scheme=hwk (pseudonymous access), the server can
track the agent across requests by JWK Thumbprint ([RFC7638]). If
the agent uses the same key across multiple servers, those servers
could correlate the agent's activity. Agents MUST use distinct keys
for distinct servers to prevent cross-server correlation of
pseudonymous identity.
Hardt Expires 4 October 2026 [Page 13]
Internet-Draft AAuth-Headers April 2026
7.2. Agent Identity Disclosure
When an agent presents its identity via scheme=jwks_uri or
scheme=jwt, the server learns the agent's HTTPS URL. This reveals
which software is making the request. Servers SHOULD NOT disclose
agent identity information to third parties without the agent
operator's consent.
7.3. JWKS Fetch Side Channel
When a server fetches an agent's JWKS from jwks_uri to verify a
signature, the fetch itself reveals to the agent's JWKS host that
someone is verifying signatures for that agent.
8. Security Considerations
8.1. HTTP Message Signature Security
HTTP Message Signatures provide:
1. *Request Integrity*: The signature covers HTTP method, target
URI, and headers
2. *Replay Protection*: The created timestamp limits signature
validity
3. *Key Binding*: Signatures are bound to specific keys via
Signature-Key
8.2. Replay Protection
The 60-second validity window on the created timestamp (see
{{verification-resource}}) limits the useful lifetime of a captured
signature. The 60-second value balances clock-skew tolerance (NTP-
synchronized hosts typically drift less than 10 seconds) against
replay exposure — a shorter window would reject legitimate requests
from hosts with modest clock drift, while a longer window would widen
the replay attack surface.
Within that window, resources MUST maintain a cache of recently seen
(key thumbprint, created) pairs and reject duplicate combinations.
Without this cache, an attacker who captures a signed request can
replay it within the validity window.
Hardt Expires 4 October 2026 [Page 14]
Internet-Draft AAuth-Headers April 2026
8.3. JWKS Caching
Resources that fetch JWKS documents for signature verification SHOULD
cache the results with a TTL appropriate to their risk tolerance
(recommended: 5 minutes for auth servers, 60 minutes for resources).
JWKS endpoints SHOULD support standard HTTP caching headers (Cache-
Control, Expires) per ([RFC9111]).
When signature verification fails due to an unknown key, the server
SHOULD re-fetch the JWKS once before returning an unknown_key error,
to handle key rotation.
9. IANA Considerations
9.1. HTTP Header Field Registration
This specification registers the following entry in the "Hypertext
Transfer Protocol (HTTP) Field Name Registry" ([RFC9110],
Section 16.3.1):
* Header Field Name: AAuth-Requirement
* Status: permanent
* Structured Type: Dictionary
* Reference: This document
* Header Field Name: AAuth-Error
* Status: permanent
* Structured Type: Dictionary
* Reference: This document
9.2. AAuth Requirement Level Registry
This specification establishes the AAuth Requirement Level Registry.
The initial contents are:
Hardt Expires 4 October 2026 [Page 15]
Internet-Draft AAuth-Headers April 2026
+=============+===============+
| Value | Reference |
+=============+===============+
| pseudonym | This document |
+-------------+---------------+
| identity | This document |
+-------------+---------------+
| interaction | This document |
+-------------+---------------+
| approval | This document |
+-------------+---------------+
Table 2
New values may be registered following the Specification Required
policy ([RFC8126]).
9.3. AAuth Error Code Registry
This specification establishes the AAuth Error Code Registry. The
initial contents are:
+=======================+===============+
| Value | Reference |
+=======================+===============+
| invalid_request | This document |
+-----------------------+---------------+
| invalid_input | This document |
+-----------------------+---------------+
| invalid_signature | This document |
+-----------------------+---------------+
| unsupported_algorithm | This document |
+-----------------------+---------------+
| invalid_key | This document |
+-----------------------+---------------+
| unknown_key | This document |
+-----------------------+---------------+
| invalid_jwt | This document |
+-----------------------+---------------+
| expired_jwt | This document |
+-----------------------+---------------+
Table 3
New values may be registered following the Specification Required
policy ([RFC8126]).
Hardt Expires 4 October 2026 [Page 16]
Internet-Draft AAuth-Headers April 2026
10. Design Rationale
10.1. Why Not Extend WWW-Authenticate?
WWW-Authenticate ([RFC9110], Section 11.6.1) tells the client which
authentication scheme to use. Its challenge model is "present
credentials" — it cannot express progressive requirements,
authorization, or deferred approval, and it cannot appear in a 202
Accepted response.
AAuth-Requirement coexists with WWW-Authenticate. A 401 response MAY
include both headers, and the client uses whichever it understands:
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="api"
AAuth-Requirement: requirement=identity
A 402 response MAY include WWW-Authenticate for payment (e.g., the
Payment scheme defined by the Micropayment Protocol
([I-D.ryan-httpauth-payment])) alongside AAuth-Requirement for
authentication or authorization:
HTTP/1.1 402 Payment Required
WWW-Authenticate: Payment id="x7Tg2pLq", method="example",
request="eyJhbW91bnQiOiIxMDAw..."
AAuth-Requirement: requirement=pseudonym
11. Implementation Status
_Note: This section is to be removed before publishing as an RFC._
This section records the status of known implementations of the
protocol defined by this specification at the time of posting of this
Internet-Draft, and is based on a proposal described in [RFC7942].
The description of implementations in this section is intended to
assist the IETF in its decision processes in progressing drafts to
RFCs.
The following implementations are known at the time of writing:
* *@aauth npm packages* (https://www.npmjs.com/org/aauth):
(https://www.npmjs.com/org/aauth):) JavaScript/TypeScript
libraries implementing HTTP Message Signatures and AAuth-
Requirement processing for agents and servers.
Hardt Expires 4 October 2026 [Page 17]
Internet-Draft AAuth-Headers April 2026
* *aauth-implementation* (https://github.com/christian-posta/aauth-
implementation): (https://github.com/christian-posta/aauth-
implementation):) Python library implementing HTTP Message
Signatures (RFC 9421), AAuth request signing/verification, and
Signature-Key header support. Author: Christian Posta.
12. Document History
_Note: This section is to be removed before publishing as an RFC._
* draft-hardt-aauth-headers-00
- Initial submission, renamed from draft-hardt-aauth-header
- Added AAuth-Error header with extensible error code registry
- Added interaction and approval requirement levels
- Added url parameter to interaction for self-contained challenge
- Renamed terminology from "resource" to "server"
13. Acknowledgments
TBD
14. References
14.1. Normative References
[I-D.hardt-httpbis-signature-key]
Hardt, D. and T. Meunier, "HTTP Signature-Key Header",
Work in Progress, Internet-Draft, draft-hardt-httpbis-
signature-key-02, 2 March 2026,
<https://datatracker.ietf.org/doc/html/draft-hardt-
httpbis-signature-key-02>.
[I-D.ryan-httpauth-payment]
Ryan, B., Moxey, J., Meagher, T., Weinstein, J., and S.
Kaliski, "The "Payment" HTTP Authentication Scheme", Work
in Progress, Internet-Draft, draft-ryan-httpauth-payment-
01, 17 March 2026, <https://datatracker.ietf.org/doc/html/
draft-ryan-httpauth-payment-01>.
[RFC6979] Pornin, T., "Deterministic Usage of the Digital Signature
Algorithm (DSA) and Elliptic Curve Digital Signature
Algorithm (ECDSA)", RFC 6979, DOI 10.17487/RFC6979, August
2013, <https://www.rfc-editor.org/info/rfc6979>.
[RFC7517] Jones, M., "JSON Web Key (JWK)", RFC 7517,
DOI 10.17487/RFC7517, May 2015,
<https://www.rfc-editor.org/info/rfc7517>.
Hardt Expires 4 October 2026 [Page 18]
Internet-Draft AAuth-Headers April 2026
[RFC7638] Jones, M. and N. Sakimura, "JSON Web Key (JWK)
Thumbprint", RFC 7638, DOI 10.17487/RFC7638, September
2015, <https://www.rfc-editor.org/info/rfc7638>.
[RFC8032] Josefsson, S. and I. Liusvaara, "Edwards-Curve Digital
Signature Algorithm (EdDSA)", RFC 8032,
DOI 10.17487/RFC8032, January 2017,
<https://www.rfc-editor.org/info/rfc8032>.
[RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for
Writing an IANA Considerations Section in RFCs", BCP 26,
RFC 8126, DOI 10.17487/RFC8126, June 2017,
<https://www.rfc-editor.org/info/rfc8126>.
[RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol
Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018,
<https://www.rfc-editor.org/info/rfc8446>.
[RFC8941] Nottingham, M. and P. Kamp, "Structured Field Values for
HTTP", RFC 8941, DOI 10.17487/RFC8941, February 2021,
<https://www.rfc-editor.org/info/rfc8941>.
[RFC9110] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke,
Ed., "HTTP Semantics", STD 97, RFC 9110,
DOI 10.17487/RFC9110, June 2022,
<https://www.rfc-editor.org/info/rfc9110>.
[RFC9421] Backman, A., Ed., Richer, J., Ed., and M. Sporny, "HTTP
Message Signatures", RFC 9421, DOI 10.17487/RFC9421,
February 2024, <https://www.rfc-editor.org/info/rfc9421>.
14.2. Informative References
[RFC5905] Mills, D., Martin, J., Ed., Burbank, J., and W. Kasch,
"Network Time Protocol Version 4: Protocol and Algorithms
Specification", RFC 5905, DOI 10.17487/RFC5905, June 2010,
<https://www.rfc-editor.org/info/rfc5905>.
[RFC7518] Jones, M., "JSON Web Algorithms (JWA)", RFC 7518,
DOI 10.17487/RFC7518, May 2015,
<https://www.rfc-editor.org/info/rfc7518>.
[RFC7942] Sheffer, Y. and A. Farrel, "Improving Awareness of Running
Code: The Implementation Status Section", BCP 205,
RFC 7942, DOI 10.17487/RFC7942, July 2016,
<https://www.rfc-editor.org/info/rfc7942>.
Hardt Expires 4 October 2026 [Page 19]
Internet-Draft AAuth-Headers April 2026
[RFC9111] Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke,
Ed., "HTTP Caching", STD 98, RFC 9111,
DOI 10.17487/RFC9111, June 2022,
<https://www.rfc-editor.org/info/rfc9111>.
[RFC9530] Polli, R. and L. Pardue, "Digest Fields", RFC 9530,
DOI 10.17487/RFC9530, February 2024,
<https://www.rfc-editor.org/info/rfc9530>.
[x402] x402 Foundation, "x402: HTTP 402 Payment Protocol", 2025,
<https://docs.x402.org>.
Author's Address
Dick Hardt
Hellō
Email: dick.hardt@gmail.com
Hardt Expires 4 October 2026 [Page 20]