AAuth Events

AAuth Events Hellō

dick.hardt@gmail.com

Security TBD agent events webhooks async subscribe http identity This document defines AAuth Events — an event subscription and delivery mechanism for agents operating under the 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.

Introduction

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.

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.

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.

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 () as an AAuth R3 vocabulary ().

Relationship to Existing Standards AAuth Events builds on the AAuth Protocol () and HTTP Signature Keys (). It provides the transport and subscription mechanisms that 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.

Conventions and Definitions {::boilerplate bcp14-tagged}

Terminology Terms defined in 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 ().
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.

Protocol Overview AAuth Events involves four phases: setup, subscription registration, event delivery from resource to AP, and event delivery from AP to agent.

AAuth Events Protocol Overview | | | | | | subscribe | | | token | | |<------------| | | | | | (2) signed request | | w/ subscribe token | |------------------------------------->| | | | | 200 OK | |<-------------------------------------| | | | | | ... time passes ... | | | | | | (3) POST event token. | | | (+ optional payload) | | |<-----------------------| | | | | | 202 Accepted | | |----------------------->| | | | | (4) event | | | token + | | | payload | | |<------------| | ]]>

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 for examples.
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.
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 (). The optional request body carries the AsyncAPI-defined payload for the event type, and the event token carries its digest.
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 for examples.

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. 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 (, Metadata Documents) before using its event_endpoint. Before fetching the AP's metadata or posting to its event_endpoint, a resource applies egress admission (, Scheme-Specific Risks).

Subscribe Token

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 (, 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 ().
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 () 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 ). The resource includes the eid in every event token it issues for this subscription.
jti: Unique token identifier (, 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 ). 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:

Presentation The agent presents the subscribe token as the Signature-Key JWT on the subscription registration request, under the jwt scheme: 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 (, 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.

Verification The resource MUST verify the subscribe token as follows:

Verify the token per (, 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.
Verify aud matches the resource's own URL.
Verify cnf.jwk matches the key used to sign the HTTP request.
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 (, 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.

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.

Subscription Registration

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 and registers the subscription.

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. This specification defines a pre-authorized subscription URL pattern for protected subscriptions:

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.
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.
The agent obtains a subscribe token from its AP.
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.
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 ) 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: Example subscription registration from step 4: 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 () so that agents that discover the resource's event capabilities through its AsyncAPI document know to obtain the URL from a prior API response.

Event Token

Structure When an event fires, the resource issues an event token: a JWT signed by the resource with the following claims: Header:

alg: per (, 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 (). A resource that delivers events makes signed calls, so its resource metadata carries jwks_uri (, 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 (, Agent Identifiers).
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 (): 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 ), and body_s256 binds the token to that body. Example event token payload:

Event Delivery: Resource to AP

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 (). The POST body is the AsyncAPI-defined payload for the event type (OPTIONAL — omitted if the event carries no payload): 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 (): 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 ). The AP forwards both the event token and the payload body to the agent. The signature covers the base components of (, 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. 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.

AP Validation The AP MUST validate the event delivery request as follows:

Extract the event token JWT from the Signature-Key header (the self-jwt scheme). Verify it per (, Common JWT Verification), with typ aa-event+jwt and dwk aauth-resource.json. Verify cnf is absent, per the self-jwt scheme ().
The AP MAY deduplicate on (iss, jti) and drop a delivery it has already recorded.
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.
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.
Look up the subscription record by eid. If no active subscription exists for this eid, return 404.
Verify iss matches the resource recorded at subscription time (the aud of the subscribe token for this eid).
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.
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: 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 (, 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 (, Polling Error Codes) and rate_limited at a revocation endpoint (, Revocation Response) — both mean come back later.

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. See for non-normative examples of AP-to-agent delivery for different platforms.

Agent Verification Upon receiving an event token (and optional payload) from the AP, the agent MUST:

Verify the token per (, 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.
Verify aud matches the agent's own identifier.
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.
Look up eid in the agent's local context mapping to recover the context associated with this subscription.
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.

Event Discovery Resources describe their event capabilities using AsyncAPI () as an AAuth R3 vocabulary ().

R3 Vocabulary Identifier The vocabulary identifier for AAuth Events is urn:aauth:vocabulary:asyncapi, registered in the AAuth R3 Vocabulary Registry by R3 (), which also defines the operation entry format. Resources that support AAuth Events SHOULD declare this vocabulary in their AAuth resource metadata:

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

Security Scheme Resources MUST declare the AAuth subscribe token security scheme as follows: 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: Operations that require a pre-authorized subscription URL (see ) 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.

Example AsyncAPI Document 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 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 ]]>

Security Considerations

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 . This prevents a compromised resource from hijacking another resource's subscription channel.

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 (). A party without the resource's private key cannot forge a valid event token. There are no shared secrets in AAuth Events.

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

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.

Pre-Authorized Subscription URL Security The subscription ticket URL (see ) 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 (, 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.

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.

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 requires egress admission (, Scheme-Specific Risks) before a resource fetches the AP's metadata or posts to its event_endpoint.

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.

Privacy Considerations

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 (, 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.

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 (, Why a PS Reports Nothing to the Agent Provider). It is inherent in the AP acting as the agent's inbox.

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 ), 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 (, Resource Access).

IANA Considerations

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 (, Section 4.1.9).

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
Interoperability considerations: N/A
Published specification: This document,
Applications that use this media type: AAuth agent providers, agents, and resources
Fragment identifier considerations: N/A

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
Interoperability considerations: N/A
Published specification: This document,
Applications that use this media type: AAuth resources, agent providers, and agents
Fragment identifier considerations: N/A

JWT Claims Registrations This specification registers the following claims in the IANA "JSON Web Token Claims" registry established by :

Claim Name	Claim Description	Change Controller	Reference
`eid`	Event ID: the AP-generated identifier of a subscription, in subscribe tokens and event tokens	IETF	This document,
`max_uses`	The number of event tokens the AP accepts for a subscription, in a subscribe token	IETF	This document,
`body_s256`	SHA-256 hash of the request body delivered with an event token	IETF	This document,

Implementation Status Note: This section is to be removed before publishing as an RFC. TBD

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

Acknowledgments The author would like to thank reviewers for their feedback on concepts and earlier drafts: Rohit Khare.

References Normative References AAuth Rich Resource Requests (R3) Hellō HTTP Signature Keys Hellō Cloudflare AAuth Protocol Hellō Informative References AsyncAPI Specification 3.0.0 AsyncAPI Initiative AAuth Bootstrap Guidance Hellō

Design Rationale This appendix explains the key design decisions in AAuth Events and the alternatives considered.

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.

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.

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.

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.

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

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.

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

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.

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.

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

Comparison to Existing Patterns

	AAuth Events	Webhooks	WebSub	CIBA (ping)	Web Push
Receiver needs public URL	No	Yes	Yes	Yes	No
Caller identity	Cryptographic (resource key)	HMAC shared secret	None	Client creds	Push service
Subscriber identity at resource	Agent identifier (`sub`)	None	None	Client ID	Subscription ID
Per-operation subscription	Yes	No (account-level)	No	Yes	No
General event types	Yes	Yes	Yes	No (auth only)	Yes
Standard description format	AsyncAPI (R3)	Proprietary	Atom/RSS	N/A	None

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 for agent token acquisition.

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.

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.

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.

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 (), 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.