Add `class` claim for grouping agent instances

[dickhardt]

Background

AAuth's per-instance agent identity (aauth:local@domain) gives each runtime its own identifier and signing key — great for per-instance authorization, revocation, and audit. But there's no first-class way to group instances of the same product.

A user installing Planner today has to consent to each Planner instance separately. A new install or container restart triggers re-consent. There's no way to say "I trust any Planner instance from vendor.example."

Proposal

Add an OPTIONAL class claim to the agent token.

{
  "iss":   "https://vendor.example",
  "sub":   "aauth:planner.7f3c@vendor.example",
  "cnf":   { "jwk": ... },
  "class": "planner"
}

Semantics:

• class is an opaque string defined by the AP.
• A class is identified by the tuple (iss, class). Verifiers MUST scope all class comparisons to that tuple.
• Comparison is exact string equality.

Where it lives:

• Only in the agent token. NOT copied to auth tokens.

Who enforces it:

• The PS only. PS uses class for grant matching. When a user consents at class granularity, the PS records (user, iss, class) → {scopes, ...}. Future instances of the same class match the existing grant without re-consent.

Storage is implementation choice. PSes can synthesize an internal key like https://vendor.example/planner for indexing, or use any other scheme. The wire format stays minimal.

No hierarchy. Class strings are flat. APs may use any internal naming convention but the protocol does exact equality only.

Rationale

Why class at all

Per-instance identity without a category concept means per-instance consent — too fine-grained for users in practice. Every major AI agent identity system has converged on having a class-like concept:

• Microsoft Foundry / Entra Agent ID: agent identity blueprints "establish the category of agent through type classification" (e.g., "Contoso Sales Agent"). Each agent identity is an instance of a blueprint. InheritDelegatedPermissions lets instances inherit permissions from the blueprint to "reduce consent complexity for multi-instance scenarios."
• Google OAuth (cross-client identity): project-wide consent — "when a user has granted access to a particular scope to any client ID in a project, the grant indicates the user's trust in the whole application."
• Karl McGuinness's client_instance_assertion draft: separates client_id (logical class) from sub (instance).
• Auth0, Okta, Ping: all building agent identity products with class-like categorization.

AAuth's class claim is the same pattern in our terminology: AP labels what kind of agent an instance is.

Why flat (no hierarchy)

Three reasons:

1. No production system uses hierarchical class. Microsoft blueprints are flat. Google projects are flat. Karl's client_id is flat. A hierarchical AAuth class would put us in a club of one.

2. Hierarchy use cases are covered by other primitives. "User consents to /planner; should cover sub-agents" — sub-agents get authorization via parent delegation, not class match. "Reject sub-agents for sensitive scope" — handled by the act != ∅ check, not class depth. "Resource policy by class subtree" — class is PS-only; resources don't see it.

3. Implementation cost vs. benefit is poor. Hierarchy requires prefix-matching DB queries, normalization rules, depth concept, "most specific match wins" semantics. Flat equality is one query.

Why PS-only

The PS is the consent/grant authority. Class exists for consent grouping. Pushing class into auth tokens is propagating an input that's already been consumed by the only party that uses it.

Open questions

1. Does anyone have a real cross-deployment use case for hierarchical class that the flat model can't express?
2. When class is omitted, the PS treats the agent purely by agent identifier (today's behavior). Good?

References

• Microsoft Foundry Agent Identity
• Google Cross-client Identity
• Karl McGuinness — client-instance-assertion
• Auth0 for AI Agents
• Okta agentic identity

[christian-posta]

I went back and forth a few times in my head..... and i've landed at: I think I like it, but there are some things to check:

Right now, an Agent Provider (AP -- formerly Agent Server) is the issuing authority for an agent instance. On its own, it can model the idea of a "class". That is, any agent issued from an AP already has a natural grouping for consent. For example the https://ap.cursor.com issues cursor agent instance tokens from this AP. They are for Cursor wherever cursor may run (web/desktop/mobile). Cursor is the "class". And claude agents could have their own AP. And OpenClaw etc.

But using an AP to issue multiple agent classes is a very real usecase. For example, a personal AP. I run my own AP, but i want it to issue identity for multiple "types" of agents. This is where the "class" proposal comes in, I believe. Again, giving a way to group consent.

But I think one of the scenarios we discussed is when aauth:supply-chain-agent.web@planning.acme.com on behalf of ceposta hands off to aauth:supply-chain-agent.desktop@planning.acme.com on behalf of ceposta to work on the same session. I think the class claim may not be helpful here?

Maybe we leave it to convention where aauth:supply-chain-agent becomes the agent identity, anything after the '.' is a classifier that describes agent surface (web, desktop, mobile, mainframe, others??). consent grouped by agent identity, and just leave the classifier to influence policy decisions at runtime?

Or with the "class" claim, i guess we'd have

{
  "iss":   "https://vendor.example",
  "sub":   "aauth:supply-chain-agent.web@vendor.example",
  "cnf":   { "jwk": ... },
  "class": "supply-chain-agent"
}

?

[dasiths]

Should we strive to infer the class based on the sub and introduce a convention like namespacing which allows for both this use case and also potentially sub-agents like in #23 ?

[dickhardt]

@christian-posta Agree that that the AP was a "class" -- what may not be clear in the text above is that we are introducing a new name space for grants. We have the agent identifier:aauth:agent@vendor.example now, and we are adding that AP+class https://vendor.example + planning (which could be stored as https://vendor.example/planning)

I currently have in the protocol that the agent can declare the surface (platform) of web, desktop, mobile, self-hosted, workload when it calls the PS, and include a device description -- these would mainly be to help to identify an agent in logs, summaries, grant lists.

If the sub value is aauth:supply-chain-agent.web@vendor.example, then I think that is the agent identifier, not aauth:supply-chain-agent@vendor.example -- the identifier should be relatively opaque to a verifier.

wrt the agent with no class wanting to get a grant for any agent from a given AP when calling a PS -- the AP could always include a class, perhaps "default" -- or we could have the agent present "*" as the class when calling the PS -- the latter is slightly more flexible as the AP as parent class is always available.

I'm going to create a new issue to discuss different surfaces accessing the same session.

[dickhardt]

@dasiths I think inferring the class from the sub would likely be problematic -- I prefer relatively opaque identifiers -- I'm thinking the class is only used by the PS or AS to enable granting access to agents of the same shape / class so the person does not have to grant access to each one agent individually.

I see class and sub agents as being orthogonal concepts and serving different purposes. A class grant allows any agent from the same AP and class to have access. Sub agent allows a parent to get attenuated access for a sub agent.

Is there a different use of class that you are thinking of?

[dickhardt]

@mcguinness thoughts?

[dickhardt]

There is an issue with mulit-tenant APs -- an agent with a class can act for any tenant with the scope -- which is not what a tenant of the AP wants.

Multi-tenant APs: add tenant to scope class grants

Class as defined here works cleanly when the AP is per-user or per-tenant (alice.vendor.example, customer.vendor.example) — iss is enough to scope the grant. It does not work for genuinely multi-tenant APs (vendor.example serving everyone): Alice's aauth:planner.X@vendor.example and Bob's aauth:planner.Y@vendor.example both match (iss=vendor.example, class=planner), and the PS has no way to tell them apart without per-instance enrollment — which is the friction class is meant to remove.

The fix is to add an OPTIONAL tenant claim to the agent token. This doesn't break the AP-knows-nothing-about-users property: tenant is something the AP already manages publicly (orgs, customer accounts, billing scopes).

Shape

{
  "iss":    "https://vendor.example",
  "sub":    "aauth:planner.7f3c@vendor.example",
  "cnf":    { "jwk": ... },
  "classes": [ "planner", "research"],
  "tenant": "acme"
}

Grant types

The PS already scopes everything to the person, so grants within a person's PS state come in three shapes:

• agent_id — per-instance grant (today's behavior)
• (AP, class) — class grant for per-user / per-tenant APs
• (AP, class, tenant) — class grant for multi-tenant APs

Net delta to the proposal

• Add OPTIONAL tenant claim to the agent token, semantics by reference to the existing auth-token claim and OIDC.Enterprise.
• Define class grant key as (AP, class) or (AP, class, tenant) depending on AP topology, alongside the existing per-agent_id grant.

[dickhardt]

Class token: separate AP-signed artifact, presented only to the PS

With earlier proposals, we were leaking the tenant and classes to the resource ...

Reworking the proposal to keep class and tenant out of the agent token entirely. The agent token stays exactly as it is today — no class, no tenant, no leakage of routing metadata to resources.

Class becomes a separate AP-issued artifact: the class token.

Shape

A class token is an AP-signed JWT carrying:

• iss: the AP's URL
• agent: the agent identifier (aauth:local@domain) this class token is bound to
• class: a single class string (opaque, AP-defined)
• tenant: OPTIONAL, scopes the class to a tenant for multi-tenant APs (semantics per existing auth-token tenant claim and OIDC.Enterprise)
• standard iat / exp

{
  "iss":    "https://vendor.example",
  "agent":  "aauth:planner.7f3c@vendor.example",
  "class":  "planner",
  "tenant": "acme"
}

The AP issues one class token per class the agent is permitted to activate. An agent that belongs to multiple classes gets multiple class tokens.

Presentation

The agent OPTIONALLY presents a class token when calling the PS token endpoint. Agents that don't use class don't present one — today's per-agent_id flow is unchanged.

When presenting, the agent picks the class token for whichever class it is operating as. The PS:

1. Verifies the class token signature against the AP's JWKS.
2. Verifies class_token.agent matches the agent identifier of the presenter.
3. Looks for a matching grant: (AP, class) or (AP, class, tenant).

The PS never sees classes the agent didn't choose to activate — privacy beats the array-in-agent-token approach.

Grant types

The PS already scopes everything to the user, so grants within a user's PS state come in three shapes:

• agent_id — per-instance grant (today's behavior)
• (AP, class) — class grant for per-user / per-tenant APs
• (AP, class, tenant) — class grant for multi-tenant APs

What this avoids

• Agent token unchanged → no class/tenant exposure to resources in any access mode (two-, three-, four-party).
• No classes array → the PS only learns about the class the agent activates, not the agent's full taxonomy.
• No new claim semantics inside the agent token → fewer cross-token-type considerations.

Net delta

• New artifact: AP-issued class token.
• New OPTIONAL parameter on the PS token endpoint to carry the class token.
• Class grant key at the PS is (AP, class) or (AP, class, tenant), alongside the existing per-agent_id grant.
• Agent token: no change.