HTTP AAuth Headers

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

4.2. Requirement Levels

The requirement value is an extension point. This document defines four levels:¶

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

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}}).¶

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

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

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.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).¶

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

6.2. Error Codes

AAuth-Error: error=invalid_request

AAuth-Error: error=invalid_input,
    required_input=("@method" "@authority" "@path"
    "signature-key" "content-digest")

AAuth-Error: error=invalid_signature

AAuth-Error: error=unsupported_algorithm,
    supported_algorithms=("EdDSA" "ES256")

AAuth-Error: error=invalid_key

AAuth-Error: error=unknown_key

AAuth-Error: error=invalid_jwt

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

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

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.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:¶

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:¶

New values may be registered following the Specification Required policy ([RFC8126]).¶

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