Internet-Draft AAuth-Events September 2026
Hardt Expires 1 April 2027 [Page]
Workgroup:
TBD
Internet-Draft:
draft-hardt-aauth-events-00
Published:
Intended Status:
Standards Track
Expires:
Author:
D. Hardt
Hellō

AAuth Events

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.

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.

▲

Table of Contents

1. Introduction

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.

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

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:

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.

  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

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:

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:

{
  "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:

  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.

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:

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:

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

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.

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:

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.

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

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 

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

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.

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.

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
  • 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]:

Table 1
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, Section 6
max_uses The number of event tokens the AP accepts for a subscription, in a subscribe token IETF This document, Section 6
body_s256 SHA-256 hash of the request body delivered with an event token IETF This document, Section 8

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.

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)", , <https://datatracker.ietf.org/doc/draft-hardt-aauth-r3>.
[I-D.hardt-httpbis-signature-key]
Hardt, D. and T. Meunier, "HTTP Signature Keys", , <https://datatracker.ietf.org/doc/draft-hardt-httpbis-signature-key>.
[I-D.hardt-oauth-aauth-protocol]
Hardt, D., "AAuth Protocol", , <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, , <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, , <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, , <https://www.rfc-editor.org/info/rfc7800>.

18.2. Informative References

[AsyncAPI]
AsyncAPI Initiative, "AsyncAPI Specification 3.0.0", , <https://www.asyncapi.com/docs/reference/specification/v3.0.0>.
[I-D.hardt-aauth-bootstrap]
Hardt, D., "AAuth Bootstrap Guidance", , <https://datatracker.ietf.org/doc/draft-hardt-aauth-bootstrap>.

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.

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.

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.

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.

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

Table 2
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

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.

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ō