Can you clarify the R3 documents?

[christian-posta]

If an agent makes a request for multiple R3 operations and that spans multiple R3 documents, how is that handled for the resource token/R3 spec? i see a single r3_url and sha256

A calendar resource has two R3 documents:

// R3 doc A — https://calendar.example.com/r3/read
{
  "type": "urn:example:calendar:read",
  "operations": [
    { "operationId": "listEvents" },
    { "operationId": "getEvent" }
  ]
}

// R3 doc B — https://calendar.example.com/r3/write
{
  "type": "urn:example:calendar:write",
  "operations": [
    { "operationId": "createEvent" },
    { "operationId": "updateEvent" }
  ]
}

An agent requests:

{
  "r3_operations": {
    "vocabulary": "urn:aauth:vocabulary:openapi",
    "operations": [
      { "operationId": "listEvents" },
      { "operationId": "createEvent" }
    ]
  }
}

listEvents is in doc A, createEvent is in doc B. The resource token can only carry one r3_uri/r3_s256. What should the resource do?

[dickhardt]

The R3 document as currently written supports only one vocabulary, but you can have many operations in the same R3 document. Guessing that is not clear in the doc?

[christian-posta]

I think I’m still fuzzy on how type relates to operations in the R3 JSON. Is type basically the resource’s name for an authorization bundle, and operations the concrete API surface covered by that bundle (in the advertised vocabulary)?

Separately, my mental model is: the agent discovers operationIds dynamically from OpenAPI (etc.), then requests auth for the subset it intends to call via r3_operations — including combinations that might cross how we partition access internally (e.g. read vs write). The part I’m stuck on is: the token only carries one r3_uri/r3_s256, so if we maintain multiple R3 docs at different URLs, is the intended deployment pattern “don’t do that; keep one doc with many operations”, or “issue a composite doc at one URL”, or “split into multiple token exchanges”?

If the answer is “one doc, many operations”, maybe call that out explicitly when describing the mapping from r3_operations → resource token.

[dickhardt]

I'm looking at the type and am now fuzzy on what that is supposed to do -- there may have been some drift between my intent and the final doc -- let me reconcile and get back to you ...

wrt. r3 docs -- I'm thinking:

don’t do that; keep one doc with many operations

or

split into multiple token exchanges

Does that align with how you would like to use them?

[nickgamb-strata]

Interesting thread - we hit a similar tension from the governance side.

We've been implementing AAuth Mission Contracts for MCP tool governance (PR #10 has our proposed extensions). One pattern that emerged was "mission template discovery" - the PS publishes structured templates describing common mission types with suggested tools and constraints.

The parallel here: when an agent's intent spans what a resource would naturally partition into separate authorization bundles, who resolves that - the resource, the agent, or the PS?

In our implementation, the PS. The agent proposes a mission in terms of what it wants to accomplish, and the PS maps that to the appropriate authorization requests. If a mission needs listEvents + createEvent across different R3 docs, the PS handles multiple token exchanges behind the scenes - the agent just sees one approved mission.

That aligns with Dick's leaning toward "one doc, many operations" or "split into multiple token exchanges" - the PS can abstract that split from the agent.

On the type field: in our template model, each template groups operations by intent rather than API surface. "Account Inquiry" vs "Account Management" rather than "read" vs "write." Worth considering whether R3 type should reflect the resource's access model or the user's intent model, since those don't always align.

Happy to share more from the implementation side.