AAuth Events
draft-hardt-aauth-events-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-09-28 | ||
| 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-events-00
TBD D. Hardt
Internet-Draft Hellō
Intended status: Standards Track 28 September 2026
Expires: 1 April 2027
AAuth Events
draft-hardt-aauth-events-00
Abstract
This document defines AAuth Events — an event subscription and
delivery mechanism for agents operating under the AAuth Protocol
([I-D.hardt-oauth-aauth-protocol]). It specifies the subscribe token
that agents use to register callbacks with resources, the event token
that resources deliver when events fire, and the delivery path
through the Agent Provider (AP). AAuth Events enables agents to
receive asynchronous notifications without requiring a public
endpoint, using the cryptographic identity established by the AAuth
Protocol.
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 1 April 2027.
Hardt Expires 1 April 2027 [Page 1]
Internet-Draft AAuth-Events September 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
1.1. Agents Cannot Receive Webhooks . . . . . . . . . . . . . 4
1.2. The Agent Provider as Inbox . . . . . . . . . . . . . . . 4
1.3. An Open Event Network . . . . . . . . . . . . . . . . . . 5
1.4. What AAuth Events Provides . . . . . . . . . . . . . . . 5
1.5. Relationship to Existing Standards . . . . . . . . . . . 6
2. Conventions and Definitions . . . . . . . . . . . . . . . . . 6
3. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 6
4. Protocol Overview . . . . . . . . . . . . . . . . . . . . . . 7
5. AP Metadata . . . . . . . . . . . . . . . . . . . . . . . . . 8
6. Subscribe Token . . . . . . . . . . . . . . . . . . . . . . . 8
6.1. Structure . . . . . . . . . . . . . . . . . . . . . . . . 9
6.2. Presentation . . . . . . . . . . . . . . . . . . . . . . 10
6.3. Verification . . . . . . . . . . . . . . . . . . . . . . 10
6.4. Agent Context Mapping . . . . . . . . . . . . . . . . . . 11
7. Subscription Registration . . . . . . . . . . . . . . . . . . 11
7.1. Public Subscriptions . . . . . . . . . . . . . . . . . . 11
7.2. Protected Subscriptions . . . . . . . . . . . . . . . . . 11
8. Event Token . . . . . . . . . . . . . . . . . . . . . . . . . 13
8.1. Structure . . . . . . . . . . . . . . . . . . . . . . . . 13
9. Event Delivery: Resource to AP . . . . . . . . . . . . . . . 15
9.1. Request . . . . . . . . . . . . . . . . . . . . . . . . . 15
9.2. AP Validation . . . . . . . . . . . . . . . . . . . . . . 16
10. Event Delivery: AP to Agent . . . . . . . . . . . . . . . . . 17
10.1. Agent Verification . . . . . . . . . . . . . . . . . . . 18
11. Event Discovery . . . . . . . . . . . . . . . . . . . . . . . 18
11.1. R3 Vocabulary Identifier . . . . . . . . . . . . . . . . 18
11.2. AsyncAPI Document . . . . . . . . . . . . . . . . . . . 19
11.3. Security Scheme . . . . . . . . . . . . . . . . . . . . 19
11.4. Example AsyncAPI Document . . . . . . . . . . . . . . . 19
12. Security Considerations . . . . . . . . . . . . . . . . . . . 21
12.1. Subscribe Token Scope . . . . . . . . . . . . . . . . . 21
Hardt Expires 1 April 2027 [Page 2]
Internet-Draft AAuth-Events September 2026
12.2. Event Token Forgery . . . . . . . . . . . . . . . . . . 21
12.3. Replay Prevention . . . . . . . . . . . . . . . . . . . 21
12.4. Subscribe Token Replay at Registration . . . . . . . . . 22
12.5. Pre-Authorized Subscription URL Security . . . . . . . . 22
12.6. AP as Delivery Intermediary . . . . . . . . . . . . . . 22
12.7. Event Endpoint Egress . . . . . . . . . . . . . . . . . 23
12.8. Resource Enumeration . . . . . . . . . . . . . . . . . . 23
13. Privacy Considerations . . . . . . . . . . . . . . . . . . . 23
13.1. Agent Identifier Stability . . . . . . . . . . . . . . . 23
13.2. AP Visibility . . . . . . . . . . . . . . . . . . . . . 23
13.3. Event Content . . . . . . . . . . . . . . . . . . . . . 24
14. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 24
14.1. Media Type Registrations . . . . . . . . . . . . . . . . 24
14.1.1. application/aa-subscribe+jwt . . . . . . . . . . . . 24
14.1.2. application/aa-event+jwt . . . . . . . . . . . . . . 24
14.2. JWT Claims Registrations . . . . . . . . . . . . . . . . 25
15. Implementation Status . . . . . . . . . . . . . . . . . . . . 25
16. Document History . . . . . . . . . . . . . . . . . . . . . . 25
17. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 27
18. References . . . . . . . . . . . . . . . . . . . . . . . . . 27
18.1. Normative References . . . . . . . . . . . . . . . . . . 27
18.2. Informative References . . . . . . . . . . . . . . . . . 27
Appendix A. Design Rationale . . . . . . . . . . . . . . . . . . 28
A.1. Why the AP Is the Delivery Intermediary . . . . . . . . . 28
A.2. Why the Subscribe Token Is the Signature-Key JWT . . . . 28
A.3. Why aud in the Subscribe Token Is the Resource . . . . . 29
A.4. Why exp Is the JWT Validity Period, Not the Subscription
Lifetime . . . . . . . . . . . . . . . . . . . . . . . . 29
A.5. Why max_uses Is in the Subscribe Token . . . . . . . . . 29
A.6. Why the Event Token Is the Transport Layer, Not the Data
Layer . . . . . . . . . . . . . . . . . . . . . . . . . 30
A.7. Why the Event Token Uses the self-jwt Scheme . . . . . . 30
A.8. Why exp in the Event Token Is the Response Window . . . . 31
A.9. Why Protected Subscriptions Use a Pre-Authorized URL . . 31
A.10. Why AsyncAPI Is the Discovery Vocabulary . . . . . . . . 31
A.11. Comparison to Existing Patterns . . . . . . . . . . . . . 32
Appendix B. Non-Normative AP-to-Agent Delivery Examples . . . . 32
B.1. Workload Agents . . . . . . . . . . . . . . . . . . . . . 33
B.2. Mobile Agents . . . . . . . . . . . . . . . . . . . . . . 33
B.3. Web Agents . . . . . . . . . . . . . . . . . . . . . . . 33
B.4. Self-Hosted Agents . . . . . . . . . . . . . . . . . . . 33
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 33
1. Introduction
Hardt Expires 1 April 2027 [Page 3]
Internet-Draft AAuth-Events September 2026
1.1. Agents Cannot Receive Webhooks
Agents are often not servers with a routable endpoint. Whether
running as a workload, a mobile app, or a single-page application,
agents typically cannot receive inbound HTTP connections. Existing
event delivery mechanisms — webhooks, WebSub, callback URLs — all
assume the receiver is always-on and reachable. This assumption
fails for agents that run intermittently, execute behind NAT, or live
inside a platform that does not expose inbound HTTP.
At the same time, many interactions agents initiate are inherently
asynchronous. An agent books a medical appointment and needs to know
if an earlier slot opens. An agent monitors inventory and needs to
know when a product becomes available. An agent submits an order and
needs confirmation when it ships. In each case, the agent initiates
a synchronous request, the resource accepts it, and then the resource
needs to reach back to the agent when something changes — potentially
hours or days later.
Existing approaches each fall short:
* *Webhooks* require the agent to have a public URL. Agents do not.
* *Polling* is wasteful and imprecise. For time-sensitive events
like waitlist slots, polling is too slow and too expensive.
* *Server-Sent Events / WebSocket* require a persistent outbound
connection, which conflicts with intermittent agent workloads.
* *Message queues* (SQS, Kafka, RabbitMQ) require shared
infrastructure, are not web-standard, and have no standardized
subscription protocol across trust domains.
1.2. The Agent Provider as Inbox
The AAuth Protocol establishes that every agent has an Agent Provider
(AP) — a stable, always-on server that issues the agent its agent
token. The AP is already a first-class principal in the AAuth
ecosystem: it has its own cryptographic identity, publishes metadata
at a well-known URL, and is trusted by all parties that interact with
the agent.
AAuth Events uses the AP as the agent's permanent event inbox. A
resource that needs to notify an agent does not need to reach the
agent directly — it posts the event to the AP's event endpoint. The
AP delivers the event to the agent through whatever mechanism the AP
and agent have established. The agent does not need a public URL.
The AP is the public URL.
Hardt Expires 1 April 2027 [Page 4]
Internet-Draft AAuth-Events September 2026
1.3. An Open Event Network
The AP inbox and AAuth identity together form a decentralized event
network: no central broker, no pre-registration between parties. A
resource that has never seen an AP before can deliver to it by
resolving the AP's event endpoint from its well-known metadata and
signing the delivery with its own discoverable key. This is the
federated reachability of email without its deliverability failure.
Every delivery is cryptographically attributable to an identified
resource, the AP accepts events only for subscriptions its agents
established, and protected channels can require the person's identity
before a subscription is created. There is no barrier to entry: an
agent operator can run their own AP or use a hosted one with no
difference in protocol, and any resource with a domain and a JWKS can
deliver events.
1.4. What AAuth Events Provides
* *No public endpoint required*: The AP receives events on the
agent's behalf. AP-to-agent delivery is platform-dependent and
out of scope for this specification.
* *Cryptographic authorization*: The subscribe token is AP-signed
and restricts event delivery to a specific resource. No shared
secrets.
* *Deliverability through identity*: Every delivery is signed by an
identified resource and accepted only against an active
subscription. No spoofed events, no shared webhook secrets, no
spam.
* *Decentralized*: No central broker and no out-of-band
registration. Resources discover AP event endpoints via well-
known metadata, and APs can be self-hosted or outsourced
interchangeably.
* *Agent identity at subscription time*: The resource knows
cryptographically which agent subscribed, via the sub claim in the
subscribe token.
* *Protected and public subscriptions*: Public event channels
require only a subscribe token. Protected channels use a pre-
authorized subscription URL issued by the resource during a prior
authenticated interaction.
* *Event discovery via AsyncAPI*: Resources describe their event
channels using AsyncAPI ([AsyncAPI]) as an AAuth R3 vocabulary
([I-D.hardt-aauth-r3]).
Hardt Expires 1 April 2027 [Page 5]
Internet-Draft AAuth-Events September 2026
1.5. Relationship to Existing Standards
AAuth Events builds on the AAuth Protocol
([I-D.hardt-oauth-aauth-protocol]) and HTTP Signature Keys
([I-D.hardt-httpbis-signature-key]). It provides the transport and
subscription mechanisms that AsyncAPI ([AsyncAPI]) describes:
resources use AsyncAPI to document their event channels and payload
schemas, while AAuth Events defines how agents subscribe and how
events are delivered.
2. Conventions and Definitions
{::boilerplate bcp14-tagged}
3. Terminology
Terms defined in [I-D.hardt-oauth-aauth-protocol] are used here with
the same meaning. In particular: Agent, Agent Provider (AP), Agent
Token, Person Token, Resource, Resource Token, Auth Token, Person
Server (PS), Access Server (AS), and HTTP Sig.
This document additionally uses:
* *Subscribe Token*: A JWT issued by the AP to the agent,
authorizing a specific resource to deliver events to the AP on the
agent's behalf. Contains the Event ID and the agent's current
signing key.
* *Event ID (eid)*: An opaque, AP-generated identifier that uniquely
identifies a subscription at the AP. The agent maps the eid to
its own context. The eid is the correlation key between the
subscribe token, the AP's subscription record, and the event
token.
* *Event Token*: A JWT issued and signed by the resource when an
event fires, addressed to the agent (aud = agent identifier),
identified by its jti, and delivered to the AP's event endpoint
using the self-jwt Signature-Key scheme
([I-D.hardt-httpbis-signature-key]).
* *Event Endpoint*: An endpoint published by the AP in its metadata
at which resources deliver event tokens.
* *Subscription Ticket*: An opaque, short-lived value returned by a
resource in response to an authenticated interaction, pre-
authorizing a subsequent subscription registration call. Used
when subscription to a protected channel requires prior
authenticated context.
Hardt Expires 1 April 2027 [Page 6]
Internet-Draft AAuth-Events September 2026
4. Protocol Overview
AAuth Events involves four phases: setup, subscription registration,
event delivery from resource to AP, and event delivery from AP to
agent.
Agent AP Resource
| | |
| (1) request | |
| subscribe | |
| token | |
|------------>| |
| | |
| subscribe | |
| token | |
|<------------| |
| | |
| (2) signed request |
| w/ subscribe token |
|------------------------------------->|
| | |
| 200 OK |
|<-------------------------------------|
| | |
| | ... time passes ... |
| | |
| | (3) POST event token. |
| | (+ optional payload) |
| |<-----------------------|
| | |
| | 202 Accepted |
| |----------------------->|
| | |
| (4) event | |
| token + | |
| payload | |
|<------------| |
Figure 1: AAuth Events Protocol Overview
1. *Subscribe token acquisition (non-normative)*: The agent requests
a subscribe token from its AP. The AP generates an eid, creates
a subscription record, and issues a subscribe token. This
interaction is AP-internal and out of scope for this
specification. See Appendix B for examples.
Hardt Expires 1 April 2027 [Page 7]
Internet-Draft AAuth-Events September 2026
2. *Subscription registration*: The agent presents the subscribe
token to the resource as the Signature-Key JWT on a signed HTTP
request to the resource's subscription endpoint. The resource
validates the subscribe token, stores the eid and the AP's
issuer, from which it resolves the AP's event_endpoint at
delivery time, and registers the subscription.
3. *Event delivery — resource to AP*: When an event fires, the
resource issues an event token (a JWT signed by the resource) and
POSTs it to the AP's event_endpoint, presenting the event token
as the Signature-Key JWT using the self-jwt scheme
([I-D.hardt-httpbis-signature-key]). The optional request body
carries the AsyncAPI-defined payload for the event type, and the
event token carries its digest.
4. *Event delivery — AP to agent (non-normative)*: The AP validates
the event, looks up the subscription by eid, and delivers the
event token and any payload to the agent. This step is platform-
dependent and out of scope for this specification. See
Appendix B for examples.
5. AP Metadata
The AP MUST publish an event_endpoint field in its metadata at
/.well-known/aauth-agent.json if it supports AAuth Events. The
event_endpoint is an HTTPS URL at which the AP receives event tokens
from resources.
{
"issuer": "https://ap.example",
"jwks_uri": "https://ap.example/.well-known/jwks.json",
"event_endpoint": "https://ap.example/events"
}
The AP MAY update the event_endpoint URL at any time. Resources
resolve the AP's event_endpoint from the AP's metadata (using the iss
claim in the subscribe token to locate the AP's well-known document)
rather than caching it from the subscribe token. A resource verifies
the document per ([I-D.hardt-oauth-aauth-protocol], Metadata
Documents) before using its event_endpoint. Before fetching the AP's
metadata or posting to its event_endpoint, a resource applies egress
admission ([I-D.hardt-httpbis-signature-key], Scheme-Specific Risks).
6. Subscribe Token
Hardt Expires 1 April 2027 [Page 8]
Internet-Draft AAuth-Events September 2026
6.1. Structure
A subscribe token is a JWT with typ: aa-subscribe+jwt, issued and
signed by the AP, with the following claims:
Header:
* alg: per ([I-D.hardt-oauth-aauth-protocol], Signature Algorithms)
* typ: aa-subscribe+jwt
* kid: Key identifier (AP's signing key)
Required payload claims:
* iss: Agent Provider URL. Used by the resource to locate the AP's
metadata and event_endpoint.
* dwk: aauth-agent.json — the well-known metadata document name for
key discovery ([I-D.hardt-httpbis-signature-key]).
* sub: Agent identifier. The AAuth agent identifier
(aauth:local@domain) of the subscribing agent.
* aud: Resource URL. The resource that is authorized to deliver
events for this subscription. The resource MUST verify that its
own URL matches this claim.
* cnf: Confirmation claim ([RFC7800]) with jwk containing the
agent's current public signing key. The resource uses this key to
verify the HTTP signature on the subscription registration
request.
* eid: Event ID. An opaque string generated by the AP, unique to
the AP. The agent maps the eid to its own context (see
Section 6.4). The resource includes the eid in every event token
it issues for this subscription.
* jti: Unique token identifier ([I-D.hardt-oauth-aauth-protocol],
Common JWT Claims).
* iat: Issued-at timestamp.
* exp: Expiration timestamp. The resource MUST reject subscribe
tokens with exp in the past.
Optional payload claims:
* max_uses: A positive integer. If present, the AP MUST NOT accept
more than this many event tokens for this eid. If absent, the
subscription is unlimited. Enforcement is the AP's
responsibility; the AP informs the resource of remaining uses in
its 202 Accepted response (see Section 9). The resource SHOULD
track remaining_uses to manage subscription state — for example,
prompting the agent to re-subscribe when the subscription is
exhausted.
Example subscribe token payload:
Hardt Expires 1 April 2027 [Page 9]
Internet-Draft AAuth-Events September 2026
{
"iss": "https://ap.example",
"dwk": "aauth-agent.json",
"sub": "aauth:k7q3p9n2@ap.example",
"aud": "https://resource.example",
"cnf": { "jwk": { "kty": "OKP", "crv": "Ed25519",
"x": "...", "alg": "Ed25519" } },
"eid": "evt_8f3k2n9p",
"jti": "st-7c1e22",
"iat": 1750000000,
"exp": 1750086400,
"max_uses": 1
}
6.2. Presentation
The agent presents the subscribe token as the Signature-Key JWT on
the subscription registration request, under the jwt scheme:
POST /appointments/waitlist HTTP/1.1
Host: resource.example
Content-Type: application/json
Signature-Input: sig=("@method" "@authority"
"@path" "signature-key" "content-type");created=1750000000
Signature: sig=:...signature bytes...:
Signature-Key: sig=jwt;
jwt="eyJhbGciOiJFZDI1NTE5IiwidHlwIjoiYWEtc3Vic2NyaWJlK2p3dCIsImtpZCI6Ii4uLiJ9..."
{
"event_types": ["slot.available"]
}
On a subscription registration request the subscribe token is the
Signature-Key JWT, in place of the agent token, person token, or auth
token the agent presents on its other requests to the resource
([I-D.hardt-oauth-aauth-protocol], Keying Material). The cnf.jwk in
the subscribe token provides the key the resource uses to verify the
HTTP signature. The subscribe token is structurally analogous to the
agent token — both are AP-signed JWTs carrying cnf.jwk —
distinguished by typ.
6.3. Verification
The resource MUST verify the subscribe token as follows:
Hardt Expires 1 April 2027 [Page 10]
Internet-Draft AAuth-Events September 2026
1. Verify the token per ([I-D.hardt-oauth-aauth-protocol], Common
JWT Verification), with typ aa-subscribe+jwt and dwk aauth-
agent.json. exp is judged by the verifier's own clock; iat is not
a validity check.
2. Verify aud matches the resource's own URL.
3. Verify cnf.jwk matches the key used to sign the HTTP request.
4. Verify eid is present and non-empty.
The subscribe token is carried in the Signature-Key header, so a
subscribe token that fails any of these steps is a signature failure,
answered with 401 and Signature-Error
([I-D.hardt-oauth-aauth-protocol], Verification (Server)).
After verification, the resource stores the subscription record with
sufficient information to deliver events — at minimum {eid, iss} (the
Event ID and the AP's issuer URL). When an event fires, the resource
resolves the AP's event_endpoint from {iss}/.well-known/aauth-
agent.json at delivery time, using standard HTTP caching for the
well-known document.
6.4. Agent Context Mapping
The eid is the agent's correlation key. The agent maintains a local
mapping of eid values to internal context — for example, "eid
evt_8f3k2n9p corresponds to the appointment waitlist for Dr. Smith,
opened under the agent's current mission". This mapping is the
agent's own concern and is not defined by this specification.
7. Subscription Registration
7.1. Public Subscriptions
For event channels that do not require prior authorization, the agent
presents the subscribe token (as the Signature-Key JWT) on a signed
POST to the resource's subscription endpoint. No additional
credential is required. The resource validates the subscribe token
per Section 6 and registers the subscription.
7.2. Protected Subscriptions
Some event channels require the agent to be authorized before it can
register a subscription — for example, subscribing to events for a
specific patient's appointments, or events associated with a
particular account. In these cases, the resource does not accept
subscription registrations from arbitrary agents; only agents that
have already been authorized in an earlier interaction may register.
Hardt Expires 1 April 2027 [Page 11]
Internet-Draft AAuth-Events September 2026
This specification defines a *pre-authorized subscription URL*
pattern for protected subscriptions:
1. The agent makes an authenticated request to the resource,
presenting a person token or auth token, since a protected
subscription is bound to a person.
2. The resource, if subscription to events is available for the
context established by this interaction, returns a *subscription
ticket URL* — an HTTPS URL that encodes a short-lived, single-use
authorization to register a subscription. The ticket URL is
opaque and is valid only for the specific context (key,
operation, and resource state) established in step 1.
3. The agent obtains a subscribe token from its AP.
4. The agent presents the subscribe token (as the Signature-Key JWT)
on a signed POST to the subscription ticket URL. No person token
or auth token is required at this step; the authorization is
embedded in the URL. The request body MAY include additional
parameters as defined by the resource's AsyncAPI channel schema.
5. The resource validates the subscribe token, verifies the ticket
in the URL is valid for the calling key (the JWK Thumbprint of
the subscribe token's cnf.jwk equals the thumbprint recorded when
the ticket was issued, see Section 12.5) and has not been used
before, and registers the subscription.
The subscription ticket URL is resource-controlled: the resource
issues it, defines its scope and expiry, and enforces its single-use
constraint. The ticket is not defined by this specification beyond
the pattern above.
Example response from step 2:
{
"status": "unavailable",
"next_available": "2026-08-24",
"waitlist": {
"subscribe_url": "https://resource.example/waitlist/st_9k2m_abc123",
"event_types": ["slot.available"],
"offer_window_seconds": 300
}
}
Example subscription registration from step 4:
Hardt Expires 1 April 2027 [Page 12]
Internet-Draft AAuth-Events September 2026
POST /waitlist/st_9k2m_abc123 HTTP/1.1
Host: resource.example
Content-Type: application/json
Signature-Input: sig=("@method" "@authority"
"@path" "signature-key" "content-type");created=1750000000
Signature: sig=:...signature bytes...:
Signature-Key: sig=jwt;
jwt="eyJhbGciOiJFZDI1NTE5IiwidHlwIjoiYWEtc3Vic2NyaWJlK2p3dCIsImtpZCI6Ii4uLiJ9..."
{
"event_types": ["slot.available"]
}
The HTTP signature covers the request path (including the ticket),
cryptographically binding the subscribe token's identity to this
specific ticket URL.
The resource SHOULD include the subscription ticket URL in an
AsyncAPI channel parameter ([AsyncAPI]) so that agents that discover
the resource's event capabilities through its AsyncAPI document know
to obtain the URL from a prior API response.
8. Event Token
8.1. Structure
When an event fires, the resource issues an event token: a JWT signed
by the resource with the following claims:
Header:
* alg: per ([I-D.hardt-oauth-aauth-protocol], Signature Algorithms)
* typ: aa-event+jwt
* kid: Key identifier (resource's signing key)
Required payload claims:
* iss: Resource URL.
* dwk: aauth-resource.json — the well-known metadata document name
for key discovery ([I-D.hardt-httpbis-signature-key]). A resource
that delivers events makes signed calls, so its resource metadata
carries jwks_uri ([I-D.hardt-oauth-aauth-protocol], Resource
Metadata).
* aud: Agent identifier (aauth:local@domain). The agent MUST verify
this matches its own identifier. Agent identifiers are compared
exactly and case-sensitively ([I-D.hardt-oauth-aauth-protocol],
Agent Identifiers).
Hardt Expires 1 April 2027 [Page 13]
Internet-Draft AAuth-Events September 2026
* eid: Event ID. MUST match the eid from the subscribe token for
this subscription. The AP uses the eid to look up the
subscription record and route to the agent. The agent uses the
eid to look up its local context mapping.
* jti: Unique identifier for this event token. (iss, jti) identifies
one event; it is the deduplication key at the AP and the agent.
The eid cannot serve, since every event on a subscription carries
the same eid.
* iat: Issued-at timestamp.
* exp: Expiration timestamp. The agent MUST NOT act on an event
token with exp in the past. The meaning of exp is event-specific
— for time-sensitive events, it encodes the deadline by which the
agent must act.
Optional payload claims:
* body_s256: The base64url-encoded SHA-256 hash, without padding, of
the request body bytes the resource sends with this event token.
REQUIRED when the delivery carries a body, and absent when it
carries none. The agent receives the body from the AP and cannot
verify the resource's HTTP signature, so this claim is what lets
it verify the payload end to end.
The event token MUST NOT contain a cnf claim. The event token is a
self-issued JWT per the self-jwt Signature-Key scheme
([I-D.hardt-httpbis-signature-key]): the resource is both the JWT
issuer and the HTTP request signer, and the key identified by kid in
the resource's JWKS verifies both the JWT and the HTTP Message
Signature.
The event token is the transport and security layer. It carries no
event-specific data. Event-specific content is delivered as the POST
body alongside the event token (see Section 9), and body_s256 binds
the token to that body.
Example event token payload:
{
"iss": "https://resource.example",
"dwk": "aauth-resource.json",
"aud": "aauth:k7q3p9n2@ap.example",
"eid": "evt_8f3k2n9p",
"jti": "ev-4d2a91",
"body_s256": "30HnqDZZZKuRXvaahsaXMeL7bBJBNUT9TrTpqvOIkH8",
"iat": 1750200000,
"exp": 1750200300
}
Hardt Expires 1 April 2027 [Page 14]
Internet-Draft AAuth-Events September 2026
9. Event Delivery: Resource to AP
9.1. Request
When an event fires for an active subscription, the resource posts to
the AP's event_endpoint, presenting the event token as the Signature-
Key JWT using the self-jwt scheme
([I-D.hardt-httpbis-signature-key]). The POST body is the AsyncAPI-
defined payload for the event type (OPTIONAL — omitted if the event
carries no payload):
POST /events HTTP/1.1
Host: ap.example
Content-Type: application/json
Content-Digest:
sha-256=:30HnqDZZZKuRXvaahsaXMeL7bBJBNUT9TrTpqvOIkH8=:
Signature-Input: sig=("@method" "@authority"
"@path" "signature-key" "content-type" "content-digest");created=1750200000
Signature: sig=:...resource signing key signature bytes...:
Signature-Key: sig=self-jwt;
jwt="eyJhbGciOiJFZDI1NTE5IiwidHlwIjoiYWEtZXZlbnQrand0Iiwia2lkIjoiLi4uIn0..."
{
"event_type": "slot.available",
"slot_time": "2026-07-15T10:00:00Z"
}
The event token in Signature-Key provides the resource's identity
(iss), routing and authorization claims (eid, aud, exp), the event's
identity (jti), and the digest of the body (body_s256). Unlike agent
tokens and subscribe tokens (which use the jwt scheme with cnf.jwk),
the event token uses the self-jwt scheme
([I-D.hardt-httpbis-signature-key]): the resource is both the JWT
issuer and the HTTP request signer, so no cnf.jwk is needed. The
resource has a stable JWKS discoverable from {iss}/.well-known/{dwk},
and the AP uses the same key (identified by kid in the JWT header) to
verify both the JWT signature and the HTTP signature. The request
body structure is defined by the resource's AsyncAPI message schema
for the event type (see Section 11). The AP forwards both the event
token and the payload body to the agent.
The signature covers the base components of
([I-D.hardt-oauth-aauth-protocol], Covered Components). When the
request carries a body, it MUST also cover content-digest and
content-type, as a request to a revocation endpoint does: the event
endpoint is defined by this document rather than by the AP's own API,
and the body is what the AP forwards to the agent.
Hardt Expires 1 April 2027 [Page 15]
Internet-Draft AAuth-Events September 2026
The resource resolves the AP's event_endpoint from {iss}/.well-known/
aauth-agent.json, where iss is the subscribe token's, at delivery
time, using standard HTTP caching for the AP's well-known document.
9.2. AP Validation
The AP MUST validate the event delivery request as follows:
1. Extract the event token JWT from the Signature-Key header (the
self-jwt scheme). Verify it per
([I-D.hardt-oauth-aauth-protocol], Common JWT Verification), with
typ aa-event+jwt and dwk aauth-resource.json. Verify cnf is
absent, per the self-jwt scheme
([I-D.hardt-httpbis-signature-key]).
2. The AP MAY deduplicate on (iss, jti) and drop a delivery it has
already recorded.
3. Verify the HTTP signature using the same key (matched by kid),
per the self-jwt scheme: the JWT signing key and the HTTP signing
key are the same key, discoverable from the resource's well-known
document.
4. If the request carries a body, verify body_s256 is present and
equals the SHA-256 hash of the body bytes. If it carries none,
verify body_s256 is absent. A mismatch is a token verification
failure, answered 401 with Signature-Error: error=invalid_jwt.
5. Look up the subscription record by eid. If no active
subscription exists for this eid, return 404.
6. Verify iss matches the resource recorded at subscription time
(the aud of the subscribe token for this eid).
7. If max_uses is set in the subscribe token, verify the use count
has not been exceeded. Increment the use count atomically. If
the use limit is reached, the AP MAY mark the subscription as
complete after delivery.
8. Verify the event token aud matches the agent identifier in the
subscription record. A mismatch is a token verification failure,
answered 401 with Signature-Error: error=invalid_jwt.
If all checks pass, the AP returns 202 Accepted and proceeds with
delivery to the agent. The AP MUST NOT return 202 before the event
has been durably recorded for delivery. If max_uses was set in the
subscribe token, the AP MUST include a JSON response body with a
remaining_uses field indicating how many more event tokens the AP
will accept for this eid:
Hardt Expires 1 April 2027 [Page 16]
Internet-Draft AAuth-Events September 2026
HTTP/1.1 202 Accepted
Content-Type: application/json
{
"remaining_uses": 0
}
When remaining_uses is 0, the subscription is exhausted. The
resource SHOULD clean up its subscription record and MAY prompt the
agent to re-subscribe on the next interaction. When max_uses was not
set, the AP returns 202 Accepted with no body (or an empty JSON
object).
The AP returns 400 for malformed requests, 401 with Signature-Error
if the event token or the HTTP signature fails step 1, 3, 4, or 8, an
expired event token included ([I-D.hardt-oauth-aauth-protocol],
Verification (Server)), 403 if the resource does not match the
subscription's authorized resource, and 404 if the eid is unknown,
the subscription has expired, or max_uses has been exceeded.
Those last three are one condition from the resource's side: the AP
has no subscription that will accept this event, and the answer is to
clean up and re-subscribe. 410 Gone would say more — that there was a
subscription here and it is finished — but an AP can answer that only
while it still holds a record it has no other use for, so the
distinction would report its retention policy rather than any
protocol state. Nothing is lost by collapsing them, because
exhaustion is reported in-band: remaining_uses: 0 in the 202 of the
delivery that spent the subscription reaches the resource at the
moment it can act on it. An event posted after that is a race or a
resource that ignored the signal, and the 404 tells it what the
earlier 202 already did.
429 Too Many Requests is not used. It invites a retry, and none of
these conditions is retryable; the base protocol's two uses of it —
slow_down on a pending URL ([I-D.hardt-oauth-aauth-protocol], Polling
Error Codes) and rate_limited at a revocation endpoint
([I-D.hardt-oauth-aauth-protocol], Revocation Response) — both mean
come back later.
10. Event Delivery: AP to Agent
How the AP delivers the event token to the agent is platform-
dependent and outside the scope of this specification. The AP is the
agent's inbox; the internal mechanism is an implementation choice for
the AP and agent. Whatever the mechanism, the AP MUST deliver the
body bytes to the agent unchanged, with the event token, so that the
agent can verify body_s256.
Hardt Expires 1 April 2027 [Page 17]
Internet-Draft AAuth-Events September 2026
See Appendix B for non-normative examples of AP-to-agent delivery for
different platforms.
10.1. Agent Verification
Upon receiving an event token (and optional payload) from the AP, the
agent MUST:
1. Verify the token per ([I-D.hardt-oauth-aauth-protocol], Common
JWT Verification), with typ aa-event+jwt and dwk aauth-
resource.json. An event token whose exp has passed fails this
step: the response window has closed, and the agent MUST NOT act
on it.
2. Verify aud matches the agent's own identifier.
3. If body_s256 is present, verify the AP delivered a body and that
its SHA-256 hash equals body_s256. If body_s256 is absent,
verify no body was delivered. The agent MUST NOT act on an event
whose body does not verify.
4. Look up eid in the agent's local context mapping to recover the
context associated with this subscription.
5. Deduplicate: if the agent has already processed an event with
this jti from this iss, it SHOULD ignore the duplicate. (iss,
jti) is the idempotency key.
Once the body verifies, the agent MAY use the payload directly. The
payload structure is defined by the resource's AsyncAPI message
schema for the event type.
11. Event Discovery
Resources describe their event capabilities using AsyncAPI
([AsyncAPI]) as an AAuth R3 vocabulary ([I-D.hardt-aauth-r3]).
11.1. R3 Vocabulary Identifier
The vocabulary identifier for AAuth Events is
urn:aauth:vocabulary:asyncapi, registered in the AAuth R3 Vocabulary
Registry by R3 ([I-D.hardt-aauth-r3]), which also defines the
operation entry format. Resources that support AAuth Events SHOULD
declare this vocabulary in their AAuth resource metadata:
{
"issuer": "https://resource.example",
"r3_vocabularies": {
"urn:aauth:vocabulary:openapi": "/openapi.json",
"urn:aauth:vocabulary:asyncapi": "/asyncapi.json"
}
}
Hardt Expires 1 April 2027 [Page 18]
Internet-Draft AAuth-Events September 2026
11.2. AsyncAPI Document
The resource's AsyncAPI document describes:
* *Channels*: Event streams the agent may subscribe to. Channels
MAY use parameterized addresses (e.g.,
/waitlist/{subscriptionTicket}) when the subscription endpoint URL
is dynamic (see Section 7.2).
* *Operations*: receive operations on channels, with the security
requirement and message schema.
* *Messages*: The payload schema for each event type. The AsyncAPI
payload schema describes the event delivery POST body (see
Section 9). The AAuth event token envelope (iss, aud, eid, jti,
exp, body_s256) is implicit and not part of the AsyncAPI schema.
* *Security schemes*: The AAuth subscribe token security scheme.
11.3. Security Scheme
Resources MUST declare the AAuth subscribe token security scheme as
follows:
securitySchemes:
aauth_subscribe:
type: http
scheme: aauth-subscribe
description: >
AAuth Subscribe Token (typ: aa-subscribe+jwt), issued by the agent's Agent
Provider, presented as the Signature-Key JWT with HTTP Message Signatures.
See draft-hardt-aauth-events.
Operations that require only a subscribe token declare:
security:
- aauth_subscribe: []
Operations that require a pre-authorized subscription URL (see
Section 7.2) have no security scheme on the subscription endpoint
itself — the subscription ticket in the URL carries the
authorization. The resource SHOULD annotate such channels with a
description noting that the subscription URL is obtained from a prior
authenticated API call.
11.4. Example AsyncAPI Document
Hardt Expires 1 April 2027 [Page 19]
Internet-Draft AAuth-Events September 2026
asyncapi: 3.0.0
info:
title: Appointments Events
version: 1.0.0
channels:
waitlistPublic:
address: /appointments/waitlist/public
messages:
slotAvailable:
$ref: '#/components/messages/SlotAvailable'
waitlistProtected:
address: /appointments/waitlist/{subscriptionTicket}
description: >
Subscription URL returned by POST /appointments when no slot is
immediately available and the calling agent is authorized for
waitlist access. The subscriptionTicket is embedded in the URL
and carries the authorization context.
parameters:
subscriptionTicket:
description: Single-use ticket from the POST /appointments response.
messages:
slotAvailable:
$ref: '#/components/messages/SlotAvailable'
operations:
subscribePublicWaitlist:
action: receive
channel:
$ref: '#/channels/waitlistPublic'
security:
- aauth_subscribe: []
subscribeProtectedWaitlist:
action: receive
channel:
$ref: '#/channels/waitlistProtected'
components:
messages:
SlotAvailable:
contentType: application/json
payload:
type: object
properties:
event_type:
type: string
Hardt Expires 1 April 2027 [Page 20]
Internet-Draft AAuth-Events September 2026
const: slot.available
slot_time:
type: string
format: date-time
doctor_id:
type: string
required:
- event_type
- slot_time
securitySchemes:
aauth_subscribe:
type: http
scheme: aauth-subscribe
description: AAuth Subscribe Token as Signature-Key JWT
12. Security Considerations
12.1. Subscribe Token Scope
The aud claim in the subscribe token restricts which resource may
deliver events to the AP for this eid. If a resource attempts to
deliver events for an eid issued to a different resource, the AP MUST
reject the request Section 9. This prevents a compromised resource
from hijacking another resource's subscription channel.
12.2. Event Token Forgery
Event tokens are signed by the resource using the resource's own
signing key. The agent verifies the event token against the
resource's JWKS ([I-D.hardt-httpbis-signature-key]). A party without
the resource's private key cannot forge a valid event token. There
are no shared secrets in AAuth Events.
12.3. Replay Prevention
The AP enforces max_uses per eid, rejects event tokens with exp in
the past, and MAY deduplicate on (iss, jti). The agent deduplicates
on (iss, jti) Section 10.1. These layers prevent replay: a captured
event token cannot be re-delivered once the AP has tracked its
delivery and the agent has processed it.
Hardt Expires 1 April 2027 [Page 21]
Internet-Draft AAuth-Events September 2026
12.4. Subscribe Token Replay at Registration
A subscribe token with a valid exp could in principle be presented to
the resource's subscription endpoint more than once. An eid is
unique only within the AP that issued it, so (iss, eid) is the
deduplication key: the resource SHOULD reject subscription
registration requests for an (iss, eid) it has already registered.
Single-use enforcement of the subscription ticket URL (in protected
subscriptions) provides an additional constraint.
12.5. Pre-Authorized Subscription URL Security
The subscription ticket URL (see Section 7.2) encodes authorization
from a prior authenticated context. Resources MUST ensure that
subscription tickets are:
* Short-lived (expiry appropriate to the expected delay between
issuing and using the ticket).
* Single-use (the resource invalidates the ticket on first
successful subscription registration).
* Bound to the signing key that established the ticket. No token
the resource verified when it issued the ticket carries an agent
identifier ([I-D.hardt-oauth-aauth-protocol], Why No Agent
Identifier Reaches a Resource); what it verified is the key in
cnf. The resource MUST record the JWK Thumbprint of that key with
the ticket, and MUST verify that the thumbprint of the subscribe
token's cnf.jwk equals it when the ticket is used. The subscribe
token's sub names the agent to its AP for delivery; it is not what
binds the ticket.
12.6. AP as Delivery Intermediary
The AP sees every event token delivered to an agent. The AP
validates the event token's iss, aud, and eid claims but does not
need to inspect resource-specific payload claims. APs SHOULD
document their data retention policies for event tokens.
body_s256 lets the agent detect a payload the AP altered or
substituted. It does not stop the AP withholding or delaying an
event.
Hardt Expires 1 April 2027 [Page 22]
Internet-Draft AAuth-Events September 2026
12.7. Event Endpoint Egress
The AP chooses its event_endpoint, and anyone can operate an AP. A
resource that posted to whatever URL an AP's metadata named could be
induced to send signed requests to its own internal addresses. For
this reason Section 5 requires egress admission
([I-D.hardt-httpbis-signature-key], Scheme-Specific Risks) before a
resource fetches the AP's metadata or posts to its event_endpoint.
12.8. Resource Enumeration
A resource that exposes its AsyncAPI document publicly reveals what
event types it emits. This may be intentional (public API).
Resources that wish to restrict event type discovery MAY gate their
AsyncAPI document with AAuth authentication.
13. Privacy Considerations
13.1. Agent Identifier Stability
The sub claim in the subscribe token carries the agent's stable
identifier, and iss names its AP. An agent that subscribes at a
resource discloses both to that resource, by its own choice. This
departs from the AAuth Protocol, in which no token a resource reads
carries an agent identifier outside agent identity access and
resource-managed access ([I-D.hardt-oauth-aauth-protocol], Agent
Identity Access and Why No Agent Identifier Reaches a Resource). A
resource that receives subscribe tokens can correlate an agent's
subscription activity over time, and for a protected subscription can
link the agent to the person the ticket was issued for. This is the
intended property — the resource needs to know which agent subscribed
and which AP to deliver to. Agents and APs should be aware that
subscription registrations leave a record at the resource.
13.2. AP Visibility
Delivery through the AP necessarily shows the AP which resources its
agents subscribe at: each subscribe token it issues names the
resource in aud, and each event token it receives names the resource
in iss. This departs from the AAuth Protocol, which keeps from the
AP which resources a person uses through its agents
([I-D.hardt-oauth-aauth-protocol], Why a PS Reports Nothing to the
Agent Provider). It is inherent in the AP acting as the agent's
inbox.
Hardt Expires 1 April 2027 [Page 23]
Internet-Draft AAuth-Events September 2026
13.3. Event Content
The event token carries no event-specific data — it is the security
and routing envelope only. Event-specific content travels as the
POST body (see Section 9), which is also visible to the AP during
routing. Resources SHOULD NOT include sensitive personal data in the
payload beyond what is necessary for the agent to evaluate relevance.
Sensitive details SHOULD be fetched by the agent from the resource's
data API, on a signed request presenting the token the resource
requires for that data ([I-D.hardt-oauth-aauth-protocol], Resource
Access).
14. IANA Considerations
14.1. Media Type Registrations
This specification registers the following media types. Their
subtypes, aa-subscribe+jwt and aa-event+jwt, are the typ values of
the subscribe token and the event token ([RFC7515], Section 4.1.9).
14.1.1. application/aa-subscribe+jwt
* Type name: application
* Subtype name: aa-subscribe+jwt
* Required parameters: N/A
* Optional parameters: N/A
* Encoding considerations: binary; a JWT is a sequence of Base64url-
encoded parts separated by period characters
* Security considerations: See Section 12
* Interoperability considerations: N/A
* Published specification: This document, Section 6
* Applications that use this media type: AAuth agent providers,
agents, and resources
* Fragment identifier considerations: N/A
14.1.2. application/aa-event+jwt
* Type name: application
* Subtype name: aa-event+jwt
* Required parameters: N/A
* Optional parameters: N/A
* Encoding considerations: binary; a JWT is a sequence of Base64url-
encoded parts separated by period characters
* Security considerations: See Section 12
* Interoperability considerations: N/A
* Published specification: This document, Section 8
* Applications that use this media type: AAuth resources, agent
providers, and agents
Hardt Expires 1 April 2027 [Page 24]
Internet-Draft AAuth-Events September 2026
* Fragment identifier considerations: N/A
14.2. JWT Claims Registrations
This specification registers the following claims in the IANA "JSON
Web Token Claims" registry established by [RFC7519]:
+===========+============================+============+===========+
| Claim | Claim Description | Change | Reference |
| Name | | Controller | |
+===========+============================+============+===========+
| eid | Event ID: the AP-generated | IETF | This |
| | identifier of a | | document, |
| | subscription, in subscribe | | Section 6 |
| | tokens and event tokens | | |
+-----------+----------------------------+------------+-----------+
| max_uses | The number of event tokens | IETF | This |
| | the AP accepts for a | | document, |
| | subscription, in a | | Section 6 |
| | subscribe token | | |
+-----------+----------------------------+------------+-----------+
| body_s256 | SHA-256 hash of the | IETF | This |
| | request body delivered | | document, |
| | with an event token | | Section 8 |
+-----------+----------------------------+------------+-----------+
Table 1
15. Implementation Status
_Note: This section is to be removed before publishing as an RFC._
TBD
16. Document History
_Note: This section is to be removed before publishing as an RFC._
* draft-hardt-aauth-events-00
- The event token carries body_s256, the SHA-256 hash of the
delivery body, REQUIRED when there is a body. The AP delivers
the body unchanged, and the agent verifies it before acting,
since it cannot verify the resource's HTTP signature. The
subscribe token carries a REQUIRED jti. An event token whose
aud does not name the subscribing agent is answered 401 with
Signature-Error: error=invalid_jwt. A resource applies egress
admission before fetching the AP's metadata or posting to its
event_endpoint. Privacy Considerations state that subscribing
Hardt Expires 1 April 2027 [Page 25]
Internet-Draft AAuth-Events September 2026
discloses the agent identifier and AP to the resource, which
departs from the protocol, and that delivery shows the AP which
resources its agents subscribe at. Protected subscriptions
require a person token or auth token because they bind to a
person. Dropped the JWT type table: IANA has no such registry,
and the media type registrations carry the typ values.
- Aligned with the published AAuth Protocol -11. The subscribe
token takes the place of whichever token the agent otherwise
presents to the resource. A subscribe token or event token
that fails verification is answered 401 with Signature-Error,
and an agent MUST NOT act on an event token whose exp has
passed. Event delivery with a body covers content-digest and
content-type. A resource verifies the AP's metadata document
and deduplicates registrations on (iss, eid). Agent
identifiers are compared case-sensitively. Registered the
media types and the eid, max_uses, and body_s256 claims.
Protocol citations name their sections.
- An exhausted subscription is answered 404, with an unknown eid
and an expired subscription, rather than 429 Too Many Requests.
None of the three is retryable, while 429 invites a retry — the
meaning it carries in both of the base protocol's uses of it.
They are answered alike because an AP can distinguish them only
while it holds a record it has no other use for, which would
make the status code a report of its retention policy;
exhaustion reaches the resource in-band anyway, as
remaining_uses: 0 in the 202 of the delivery that spent the
subscription.
- Consistency pass against AAuth Protocol -11. Event tokens
carry jti, and the AP and agent deduplicate on (iss, jti);
deduplicating on eid would have dropped every event after the
first on an unlimited subscription. The protected-subscription
flow binds the ticket to the JWK Thumbprint of the subscribe
token's cnf.jwk, matching Security Considerations. iat is not a
validity check. The event payload is the POST body, not a
payload member, and the AsyncAPI message contentType is
application/json. Token alg rules and the common verification
steps point at the protocol rather than restating it. Example
JWTs use Ed25519 and the registered typ values. The AsyncAPI
vocabulary identifier is registered by R3, not defined here.
- Referenced the AAuth Protocol, AAuth Bootstrap, and R3 by their
datatracker document URLs, which track the latest revision.
- Algorithm identifiers: Ed25519 rather than the deprecated
polymorphic EdDSA; the cnf.jwk example carries the alg member
now required of every conveyed key.
- Initial draft.
Hardt Expires 1 April 2027 [Page 26]
Internet-Draft AAuth-Events September 2026
17. Acknowledgments
The author would like to thank reviewers for their feedback on
concepts and earlier drafts: Rohit Khare.
18. References
18.1. Normative References
[I-D.hardt-aauth-r3]
Hardt, D., "AAuth Rich Resource Requests (R3)", 2026,
<https://datatracker.ietf.org/doc/draft-hardt-aauth-r3>.
[I-D.hardt-httpbis-signature-key]
Hardt, D. and T. Meunier, "HTTP Signature Keys", 2026,
<https://datatracker.ietf.org/doc/draft-hardt-httpbis-
signature-key>.
[I-D.hardt-oauth-aauth-protocol]
Hardt, D., "AAuth Protocol", 2026,
<https://datatracker.ietf.org/doc/draft-hardt-oauth-aauth-
protocol>.
[RFC7515] Jones, M., Bradley, J., and N. Sakimura, "JSON Web
Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, May
2015, <https://www.rfc-editor.org/info/rfc7515>.
[RFC7519] Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token
(JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015,
<https://www.rfc-editor.org/info/rfc7519>.
[RFC7800] Jones, M., Bradley, J., and H. Tschofenig, "Proof-of-
Possession Key Semantics for JSON Web Tokens (JWTs)",
RFC 7800, DOI 10.17487/RFC7800, April 2016,
<https://www.rfc-editor.org/info/rfc7800>.
18.2. Informative References
[AsyncAPI] AsyncAPI Initiative, "AsyncAPI Specification 3.0.0", 2023,
<https://www.asyncapi.com/docs/reference/specification/
v3.0.0>.
[I-D.hardt-aauth-bootstrap]
Hardt, D., "AAuth Bootstrap Guidance", 2026,
<https://datatracker.ietf.org/doc/draft-hardt-aauth-
bootstrap>.
Hardt Expires 1 April 2027 [Page 27]
Internet-Draft AAuth-Events September 2026
Appendix A. Design Rationale
This appendix explains the key design decisions in AAuth Events and
the alternatives considered.
A.1. Why the AP Is the Delivery Intermediary
Agents are workloads, not servers. They spin up, execute, and
terminate. They run behind NAT, inside containers, or on mobile
devices. They have no stable public endpoint.
Every existing push delivery mechanism (webhooks, WebSub, CIBA ping/
push mode, W3C Web Push) assumes the subscriber has a stable HTTP
endpoint. W3C Web Push is the closest analog to what AAuth Events
does — it uses a browser push service (Google/Apple/Mozilla) as the
subscriber's stable address. AAuth Events uses the AP in this role,
with two improvements: the AP already has a trust relationship with
the agent (it issued the agent's agent token), and the subscriber's
identity is cryptographic (not just an opaque push service
subscription).
The AP-as-inbox pattern mirrors how email works: you do not need to
be online when someone sends you mail. The mail server is the stable
address. AAuth Events gives agents the same property for event
delivery.
A.2. Why the Subscribe Token Is the Signature-Key JWT
The subscribe token simultaneously serves two functions: it proves
the agent's identity (via cnf.jwk + HTTP signature) and registers the
subscription (via eid, aud, exp). Presenting it as the Signature-Key
JWT means a single signed HTTP request to the subscription endpoint
accomplishes both without a separate credential or header.
This is structurally analogous to the agent token — both are AP-
signed JWTs with cnf.jwk, distinguished by typ. The resource's
verification path is the same whether it is processing a request
under agent identity access with an agent token or a subscription
registration with a subscribe token.
The alternative — a separate header or body parameter carrying the
subscribe token alongside the agent token, person token, or auth
token the agent otherwise presents — was rejected because it requires
two credentials where the subscribe token alone is sufficient.
Hardt Expires 1 April 2027 [Page 28]
Internet-Draft AAuth-Events September 2026
A.3. Why aud in the Subscribe Token Is the Resource
The aud claim restricts event delivery authorization to a specific
resource. Only the resource named in aud may deliver events for this
eid to the AP. This prevents:
* A compromised resource from injecting events into another agent's
subscription channels.
* The AP from accepting events from unexpected callers.
The AP enforces this by matching the calling resource (identified by
its HTTP signature) against the aud in the subscribe token stored in
the subscription record.
A.4. Why exp Is the JWT Validity Period, Not the Subscription Lifetime
Subscription lifetime is a negotiation between the agent and the
resource at registration time. The resource has its own policy on
maximum subscription duration. These durations can be days or months
and are resource-specific.
The subscribe token's exp is the standard JWT validity window — how
long the resource may accept this token for registration. Conflating
JWT validity with subscription lifetime would either force a very
long-lived token (security concern: replay window) or a very short
subscription (UX concern: subscriptions expire before they're
useful).
The resource stores the subscription record with whatever lifetime
the agent and resource negotiate at registration. The subscribe
token is a registration credential, not a subscription policy
document.
A.5. Why max_uses Is in the Subscribe Token
max_uses is the AP's throttle on how many event tokens it will accept
for a given eid. It is AP-enforced, not resource-enforced. Placing
it in the subscribe token — which the AP issued and controls — makes
it AP-policy without requiring a separate AP configuration step.
For single-shot events (confirm this reservation), max_uses: 1
ensures the AP accepts exactly one event. For ongoing subscriptions,
max_uses is omitted (unlimited). When max_uses is absent, there is
no sentinel value — absence means unlimited, avoiding any need for a
special value such as -1.
Hardt Expires 1 April 2027 [Page 29]
Internet-Draft AAuth-Events September 2026
The AP informs the resource of remaining uses in the 202 Accepted
response body after each delivery. The resource SHOULD use
remaining_uses: 0 as the signal to clean up its subscription record
and prompt the agent to re-subscribe. This keeps the AP as the
enforcement point while giving the resource the state it needs to
manage the subscription lifecycle.
A.6. Why the Event Token Is the Transport Layer, Not the Data Layer
The event token carries only what is needed for security, routing,
and correlation: iss, aud, eid, jti, exp, and body_s256. It is the
cryptographic layer — the AP uses it to authenticate the resource,
look up the subscription, and verify the delivery is authorized. The
agent uses it to verify authenticity, verify the body, and look up
its context via eid.
Event-specific data travels as the POST body. The AsyncAPI message
schema for the event type defines the payload structure. This
separation keeps the JWT minimal and avoids embedding event data in a
signed-but-not-encrypted envelope. The token carries a digest of the
body instead: the agent receives the body from the AP, not from the
resource, and cannot verify the resource's HTTP signature, so
body_s256 is what carries the resource's signature over the payload
to the agent. For events where the agent needs full details beyond
the payload, it fetches them from the resource's data API, presenting
the token the resource requires for that data.
A.7. Why the Event Token Uses the self-jwt Scheme
Agent tokens and subscribe tokens use the jwt Signature-Key scheme
because they are delegation credentials: the AP issues the JWT, and
the JWT delegates HTTP signing authority to the agent's key via
cnf.jwk. The event token has no delegation — the resource issues the
JWT and signs the HTTP request itself, with the same key. The self-
jwt scheme ([I-D.hardt-httpbis-signature-key]) models exactly this:
the JWT issuer and the HTTP signer are the same party, cnf is absent,
and the key discovered from {iss}/.well-known/{dwk} (matched by kid)
verifies both the JWT and the HTTP Message Signature. Using self-jwt
lets the event token carry application claims (eid, aud, exp,
body_s256) in the Signature-Key JWT without inventing an AAuth-
specific extension to the jwt scheme.
Hardt Expires 1 April 2027 [Page 30]
Internet-Draft AAuth-Events September 2026
A.8. Why exp in the Event Token Is the Response Window
The exp claim in the event token defines how long the agent has to
respond to the event. Its meaning is event-specific: for a waitlist
slot, it is the deadline by which the agent must claim the slot; for
a shipping confirmation, it may be a much longer acknowledgment
window.
The AP delivers events in near real-time. If the AP cannot deliver
an event before its exp, the agent should not act on it (the response
window has closed). The agent verifies exp before acting.
A.9. Why Protected Subscriptions Use a Pre-Authorized URL
For protected event channels, the resource needs to verify that the
subscribing agent has been authorized in a prior interaction before
accepting the subscription. The naive approach — requiring both a
person token or auth token and a subscribe token on the subscription
call — is awkward because the two tokens serve different purposes and
conveying a person token or auth token alongside a Signature-Key
subscribe token has no established AAuth pattern.
The pre-authorized subscription URL pattern solves this cleanly:
authorization is captured in the prior authenticated interaction, and
the resource returns a ticket URL that encodes this context. The
agent then presents only the subscribe token at the ticket URL. The
HTTP signature covers the URL path (including the ticket), binding
the subscribe token's identity to this specific authorization
context.
This mirrors established patterns (OAuth authorization codes, S3
presigned URLs) while preserving the AAuth Events invariant: all
subscription endpoints accept only the subscribe token as the
Signature-Key JWT.
A.10. Why AsyncAPI Is the Discovery Vocabulary
AsyncAPI is the de facto standard for describing event-driven APIs.
It describes channels, message schemas, security requirements, and
(via parameterized addresses) dynamic subscription endpoints. The
AAuth R3 vocabulary framework already accommodates multiple
vocabularies per resource — AsyncAPI sits naturally alongside OpenAPI
for synchronous operations.
Hardt Expires 1 April 2027 [Page 31]
Internet-Draft AAuth-Events September 2026
The target reader of an AAuth resource's AsyncAPI document is an
AAuth-capable agent, not generic AsyncAPI tooling. This means the
aauth_subscribe security scheme (type: http, scheme: aauth-subscribe)
does not need to be understood by Swagger UI or code generators — it
is a declaration for the agent's benefit, interpreted per this
specification.
A.11. Comparison to Existing Patterns
+==============+=============+===========+======+======+============+
| |AAuth Events |Webhooks |WebSub|CIBA |Web Push |
| | | | |(ping)| |
+==============+=============+===========+======+======+============+
| Receiver |No |Yes |Yes |Yes |No |
| needs public | | | | | |
| URL | | | | | |
+--------------+-------------+-----------+------+------+------------+
| Caller |Cryptographic|HMAC shared|None |Client|Push service|
| identity |(resource |secret | |creds | |
| |key) | | | | |
+--------------+-------------+-----------+------+------+------------+
| Subscriber |Agent |None |None |Client|Subscription|
| identity at |identifier | | |ID |ID |
| resource |(sub) | | | | |
+--------------+-------------+-----------+------+------+------------+
| Per- |Yes |No |No |Yes |No |
| operation | |(account- | | | |
| subscription | |level) | | | |
+--------------+-------------+-----------+------+------+------------+
| General |Yes |Yes |Yes |No |Yes |
| event types | | | |(auth | |
| | | | |only) | |
+--------------+-------------+-----------+------+------+------------+
| Standard |AsyncAPI (R3)|Proprietary|Atom/ |N/A |None |
| description | | |RSS | | |
| format | | | | | |
+--------------+-------------+-----------+------+------+------------+
Table 2
Appendix B. Non-Normative AP-to-Agent Delivery Examples
How the AP delivers an event token to an agent is platform-dependent
and not specified by this document. The following examples
illustrate common patterns, paralleling the approach taken in
[I-D.hardt-aauth-bootstrap] for agent token acquisition.
Hardt Expires 1 April 2027 [Page 32]
Internet-Draft AAuth-Events September 2026
B.1. Workload Agents
A workload agent (running in a cloud function, container, or batch
job) may poll the AP for pending event tokens on startup, using an
AP-internal endpoint. The AP acts as a durable inbox — storing event
tokens until the workload polls. The workload validates and
processes pending events before beginning its primary task.
B.2. Mobile Agents
A mobile agent may receive events via the platform's native push
notification infrastructure (APNs on iOS, FCM on Android). The AP
holds a push token registered by the agent at enrollment time and
delivers event tokens to the agent via push notification. The agent
wakes on receipt, fetches the full event token from the AP if needed,
and processes it.
B.3. Web Agents
A web agent with a persistent session may receive events via a
server-sent event (SSE) or WebSocket connection that the agent
maintains to the AP. The AP streams event tokens over this
connection as they arrive.
B.4. Self-Hosted Agents
A self-hosted agent may receive events in two ways depending on
whether it manages its own AP or delegates to an external one.
If the agent acts as its own AP ([I-D.hardt-aauth-bootstrap]), it may
expose an internal event endpoint. Events are delivered directly to
this endpoint by the resource — the AP and agent are collocated.
If the agent uses an external AP service, it maintains an outbound
persistent connection (SSE, WebSocket, or a similar mechanism) to the
AP's inbox service. The AP delivers event tokens and payloads over
this connection as they arrive. The self-hosted agent does not need
a public inbound endpoint — the outbound connection to the AP is
sufficient.
Author's Address
Dick Hardt
Hellō
Email: dick.hardt@gmail.com
Hardt Expires 1 April 2027 [Page 33]