AAuth - Agentic Authorization OAuth 2.1 Extension

5.1. Step 1: Requesting the Minimal Scope AI Agent Token

In the first step, the AI Agent requests an access token with very limited scope. This scope has a very specific meaning in the context of this specification. It refers to the set of access that is permitted by an AI Agent which is completely safe and should not require the resource owner - or software or AI agents operating on their behalf - to explicitly approve. The precise set of API calls that fit under this umbrella are entirely a matter of local implementation in the resource server.¶

We call this scope the "Minimal AI Agent scope". This specification standardizes a well-known value for this scope - "ai-agent-minimal". This is similar in concept to OIDC which defines a small set of well-defined scopes [OIDC].¶

AI Agents gain access tokens associated with this scope through any of the existing OAuth2.0 grant flows.¶

For the authorization code grant flow, it is RECOMMENDED that Authorization Servers render information to the resource owner, informing them that this is an AI Agent, and they may be required to perform additional approvals to when the AI Agent does something that has some risk. It is RECOMMENDED that examples are provided on what type of access is considered risky. For example, a travel website may allow an AI Agent to list flights, or enumerate airports. However, listing of a user's travel plans or making flight changes, is considered risky.¶

In all ways, the access token obtained with this scope is a normal access token and the AI Agent can use it in the same way it uses any other access token.¶

5.2. Step 2: Access the Resource

When the AI Agent accesses a resource on the resource server using the minimal AI Agent scope, if the minimal scope associated with the token is sufficient, the resource server will accept the request and all is well.¶

However, if the AI Agent attempts to perform an action which the resource server determines is beyond the minimal AI Agent scope, it rejects the request with a 403 (Forbidden) response carrying an insufficient_scope error code in the WWW-Authenticate header, as defined in Section 3 of [RFC6750]. Alongside the scope auth-param defined by [RFC6750], the RS includes a new auth-param defined by this specification, scope_challenge. Its value is a Scope Challenge (Section 5.2.1): a JWT, signed by the RS, that carries both the set of scopes required to perform the operation and a reason - a natural language explanation of why the minimal AI Agent scope was insufficient for this particular operation. Because the challenge is signed, neither the AI Agent nor any other party between the RS and the AS can alter the scopes or the reason that will ultimately be shown to the user.¶

HTTP/1.1 403 Forbidden
WWW-Authenticate: Bearer error="insufficient_scope",
  scope="urn:example:reservations.write",
  resource_metadata="https://api.example.com/.well-known/
    oauth-protected-resource",
  scope_challenge="eyJhbGciOiJFUzI1NiIsInR5cCI6InNjb3BlLWNoYWxsZW5
    nZStqd3QiLCJraWQiOiJyczEifQ.eyJpc3MiOiJodHRwczovL2FwaS5leGFtcG
    xlLmNvbSIsImF1ZCI6Imh0dHBzOi8vYXV0aC5leGFtcGxlLmNvbSIsImlhdCI6
    MTc5MzQ2OTYwMCwiZXhwIjoxNzkzNDY5OTAwLCJqdGkiOiI5ZjFjMmUzYS00Yj
    VkLTRlNmYtOGE5Yi0wYzFkMmUzZjRhNWIiLCJjbGllbnRfaWQiOiJyZXNlcnZl
    Ym90Iiwic3ViIjoiMjQ4Mjg5NzYxMDAxIiwic2NvcGUiOiJ1cm46ZXhhbXBsZT
    pyZXNlcnZhdGlvbnMud3JpdGUiLCJyZWFzb24iOiJSZXNlcnZlQm90IHdhbnRz
    IHRvIGJvb2sgYSB0YWJsZSBmb3IgdHdvIGF0IEpvZSdzIEl0YWxpYW4gb24gRn
    JpZGF5IGF0IDlwbS4ifQ.DtsKx1Q...2Qw"

The RS MUST issue a Scope Challenge only in response to a request that presented a valid access token. A request with a missing, expired, revoked, or otherwise invalid token is rejected with the invalid_token error as usual, and no Scope Challenge is issued. The RS SHOULD also include the resource_metadata auth-param defined in Section 5.1 of [RFC9728], so that the AI Agent and the AS can locate the RS's metadata (Section 6.2).¶

This exchange is similar in structure to the step-up authentication challenge of [RFC9470], in which an RS tells a client that a token obtained with stronger authentication is required. Here, the RS tells the client that additional scopes - and the resource owner's approval - are required, and says why.¶

{
  "iss": "https://api.example.com",
  "aud": "https://auth.example.com",
  "iat": 1793469600,
  "exp": 1793469900,
  "jti": "9f1c2e3a-4b5d-4e6f-8a9b-0c1d2e3f4a5b",
  "client_id": "reservebot",
  "sub": "248289761001",
  "scope": "urn:example:reservations.write",
  "reason": "ReserveBot wants to book a table for two at Joe's
             Italian on Friday at 9pm."
}

5.3. Step 3: Initiate AAuth Grant Flow with AS

Next, the AI Agent initiates the flow defined in this specification to obtain a higher scoped, short-lived access token with the set of required scopes. To do that, it sends an HTTP POST to a new endpoint of the AS defined in this specification - the agent authorization endpoint - and includes the Scope Challenge it received from the resource server. The AS learns the required scopes and the reason from the Scope Challenge; the AI Agent does not supply them separately, and cannot modify them. The location of the agent authorization endpoint is published in the AS's metadata (Section 6.1).¶

An example of such a request is:¶

POST /agent_authorization HTTP/1.1
Host: auth.example.com
Content-Type: application/x-www-form-urlencoded
Authorization: Basic <base64(client_id:client_secret)>

grant_type=urn:ietf:params:oauth:grant-type:agent_authorization
&scope_challenge=eyJhbGciOiJFUzI1NiIsInR5cCI6InNjb3BlLWNoYWxsZW5
nZStqd3QiLCJraWQiOiJyczEifQ.eyJpc3MiOiJodHRwczovL2FwaS5leGFtcGxl
LmNvbSIsImF1ZCI6Imh0dHBzOi8vYXV0aC5leGFtcGxlLmNvbSIs...fQ.DtsKx1Q
...2Qw
&timeout=300

The following parameters are included in the body:¶

grant_type:

REQUIRED. MUST be urn:ietf:params:oauth:grant-type:agent_authorization.¶

scope_challenge:

REQUIRED. The Scope Challenge, exactly as received from the RS.¶

timeout:

OPTIONAL. The maximum time, in seconds, that the AI Agent is willing to wait for approval. See Section 5.3.1.¶

The AI Agent MUST authenticate to the agent authorization endpoint using the client authentication method registered for it, as described in Section 2.3 of [RFC6749]. This grant is defined for confidential clients only; an AS MUST reject a request from a public client with an unauthorized_client error.¶

5.4. Step 4: AS Processes Grant Request

The AS validates the client credentials as per normal OAuth processing.¶

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store

{
  "request_code": "GhiJkl-QRstuVwxyz",
  "token_endpoint": "https://auth.example.com/token",
  "user_approval_endpoint" : "https://auth.example.com/approve",
  "poll_interval": 5,
  "expires_in": 300,
  "poll_sse_endpoint":
    "https://auth.example.com/agent_authorization/sse",
  "poll_ws_endpoint":
    "wss://auth.example.com/agent_authorization/ws"
}

5.5. User Approval

The AS MUST obtain user approval in order to grant the token. It may do so using the simple approval technique defined here, or employ any number of mechanisms outside the scope of this specification to do so.¶

In this architecture, the AS plays the role of advocate for the resource owner, making sure their security interests are met. As such, it relies on a trust relationship between the resource owner and the AS.¶

Whatever technique is used, the information presented to the approver MUST be taken from the validated Scope Challenge and from the AS's own records: the registered name of the client ([RFC7591]), the identity of the resource server (for example, the resource_name from its metadata), the reason, and the human-readable description of each requested scope. The AS MUST NOT present text supplied directly by the AI Agent. See Section 8.7 for the properties the approval channel needs to have.¶

5.6. Token Retrieval

After the agent authorization request has been accepted, the AI Agent obtains its access token via one of three techniques: HTTP polling of the token endpoint, a Server-Sent Events stream, or a WebSocket connection. The following rules apply to all three:¶

• The AI Agent MUST authenticate as the client that made the agent authorization request, using its registered client authentication method. For the SSE and WebSocket endpoints, which are accessed with GET, a client that authenticates with a client secret MUST use the HTTP Basic scheme and MUST NOT place the secret in the query component; a client that authenticates with a client_assertion sends it as a query parameter.¶

• The AI Agent MUST present the request_code.¶

• The AS MUST deliver the token for a given request_code at most once, across all channels. The AI Agent MAY use more than one technique for the same request_code (for example, an SSE stream with polling as a fallback), but the token will be delivered on exactly one of them; the others will report that the request_code has been consumed.¶

• Every response that carries a token or request state MUST include Cache-Control: no-store.¶

• All endpoints MUST be served over TLS.¶

On success, the token response is a standard OAuth 2.0 token response as defined in Section 5.1 of [RFC6749]. The issued token SHOULD be short-lived, and its scope MUST NOT exceed the scope of the Scope Challenge.¶

POST /token HTTP/1.1
Host: auth.example.com
Content-Type: application/x-www-form-urlencoded
Authorization: Basic <base64(client_id:client_secret)>

grant_type=urn:ietf:params:oauth:grant-type:agent_authorization
&request_code=GhiJkl-QRstuVwxyz

HTTP/1.1 202 Accepted
Content-Type: application/json
Cache-Control: no-store
Retry-After: 5

{"status":"authorization_pending"}

HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store

{
  "access_token": "2YotnFZFEjr1zCsicMWpAA",
  "token_type": "Bearer",
  "expires_in": 900,
  "scope": "urn:example:reservations.write"
}

GET /agent_authorization/sse?request_code=GhiJkl-QRstuVwxyz HTTP/1.1
Host: auth.example.com
Accept: text/event-stream
Authorization: Basic <base64(client_id:client_secret)>

event: authorization_pending
data: {"request_code":"GhiJkl-QRstuVwxyz","expires_in":287}

: keepalive

: keepalive

event: token_response
data: {"access_token":"2YotnFZFEjr1zCsicMWpAA",
data:  "token_type":"Bearer","expires_in":900,
data:  "scope":"urn:example:reservations.write"}

event: authorization_pending
data: {"request_code":"GhiJkl-QRstuVwxyz","expires_in":287}

: keepalive

event: error
data: {"error":"access_denied",
data:  "error_description":"The user denied the request."}

GET /agent_authorization/ws?request_code=GhiJkl-QRstuVwxyz HTTP/1.1
Host: auth.example.com
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==
Sec-WebSocket-Version: 13
Sec-WebSocket-Protocol: aauth.agent-flow
Authorization: Basic <base64(client_id:client_secret)>

{"type":"authorization_pending",
 "request_code":"GhiJkl-QRstuVwxyz","expires_in":287}

{"type":"token_response",
 "access_token":"2YotnFZFEjr1zCsicMWpAA",
 "token_type":"Bearer","expires_in":900,
 "scope":"urn:example:reservations.write"}

{"type":"error","error":"access_denied",
 "error_description":"The user denied the request."}

{"type":"error","error":"expired_token",
 "error_description":"The request_code has expired."}

5.7. Error Handling and Back-Off

6.1. Authorization Server Metadata

This specification defines the following OAuth Authorization Server Metadata [RFC8414] member:¶

agent_authorization_endpoint:

URL of the AS's agent authorization endpoint (Section 5.3). An AS that supports this specification SHOULD publish it.¶

6.2. Protected Resource Metadata

A resource server that supports this specification publishes OAuth Protected Resource Metadata [RFC9728] at the well-known location derived from its resource identifier. In that metadata, the RS:¶

• MUST include jwks_uri, referencing a JWK Set that contains the public key(s) used to sign Scope Challenges. Keys used for this purpose SHOULD carry a use value of sig.¶

• SHOULD include resource_signing_alg_values_supported, listing the algorithms it uses to sign Scope Challenges.¶

• SHOULD include authorization_servers, listing the authorization servers for which it issues Scope Challenges. The AS SHOULD verify that it is listed.¶

• SHOULD include scope_descriptions_uri, defined below, unless the AS obtains scope descriptions by other means.¶

• SHOULD include resource_name, which the AS can display to the resource owner to identify the RS.¶

This specification defines one new Protected Resource Metadata member:¶

scope_descriptions_uri:

URL of the RS's Scope Descriptions Document (Appendix A). This URL MUST use the https scheme.¶

8.1. Trust Model

This specification is built on the core idea that the AI Agent is NOT TRUSTED, and the human user is seeking to gate its access. The human user does however trust the AS and RS, which is the normal situation with OAuth.¶

8.2. On Agent Identity

There is much ongoing work and discussion on how to identify AI agents on the Internet. These include WIMSE ((I-D.ietf-wimse-arch)) [I-D.ietf-wimse-workload-creds] [I-D.ietf-wimse-wpt], W3C Agent Identity [W3C-AgentId], and arguably WebBotAuth [I-D.ietf-webbotauth-httpsig-protocol].¶

This specification does not depend on an authenticated identifier that is unique to AI Agents. It restricts what the AI Agent can do not by its identity, but rather, by the baseline minimum scope it obtains.¶

The AI Agent will normally obtain this minimum scoped token by existing OAuth flows, most likely a combination of the authorization code grant flow or client credentials flow. In the former case, the AI Agent would be pre-configured to request this scope initially when a user configures it. This relies on human judgement for the author of the AI Agent (in requesting this scope) and on the resource owner (in approving it) to identify this software as one for which these reduced permissions are required. It doesn't matter whether the software is ACTUALLY an AI Agent, it only matters whether the level of trust in it is low enough to warrant this minimal scope.¶

Similarly, for AI Agents configured through the client credentials grant flow, the human user that configures the clientID and secret are trusted to select this scope as the one it requests.¶

Consequently, the security properties afforded by this specification are rooted in the human judgement of the users who author the software, configure it (in the case of client credential grants) or approve its access (in the case of authorization code grants), that the software is one for which this lower level of trust applies. In our view, this human judgement is a good thing, not a bad one.¶

It does however introduce a potential weakness - a malicious AI Agent can still avoid this specification entirely and just request access tokens through existing OAuth grant flows which give it elevated privilege. That weakness is, unfortunately, the current situation of the world we live in - with AI Agents built before we had the right types of security techniques in place to authorize their access. Consequently, it is not a security flaw in this specification per se.¶

8.3. Preventing Malicious AI Agents from Altering Reasons and Scopes

The reason and the scopes are the information on which the resource owner bases their decision. If an AI Agent could alter either, it could obtain approval for one action while presenting another - for example, by pairing a benign reason with a broader set of scopes. This specification does not trust the AI Agent to pass these unaltered. As a result, it protects them with the signatures on the scope challenge.¶

The signature uses keys shared between the AS and RS, and require no trust in the AI Agent. This ensures the AI Agent cannot manipulate keying material to adjust signatures.¶

The signature covers the reason and the required scopes, not just one of them alone. This prevents an attack wherein a malicious AI Agent could modify the scopes to be larger, with a reason that seems to imply lesser scopes.¶

8.4. Preventing Malicious AI Agents from Tricking the AS or RS

A potential attack from a malicious AI Agent is one in which it colludes with a malicious AS in order to obtain tokens which can be used against an RS it wishes to access. Similarly, a malicous AI Agent might try to fool a legitimate AS into issuing tokens by creating its own scope challenges, and getting the AS to sign them.¶

This is preventing by requiring that the AS only accept Scope Challenges from resource servers it is configured to serve. Similarly, the client_id claim binds the challenge to the AI Agent that encountered the refusal, so that a challenge obtained by one client cannot be redeemed by another. The sub claim binds it to the resource owner whose token was presented, so that an AI Agent cannot cause a different resource owner to be prompted. The jti claim and the short exp prevent a single challenge from being used to generate repeated approval prompts.¶

8.5. Preventing Token Theft via request_code Reuse

A malicious agent might try to reuse a request code which generated a previous approval to obtain a new token. Or, it might try to attack web infratructure to obtain previously used request_code values which produced a token.¶

Request code reuse is prevented in several ways.¶

First - it is protected by client authentication on every endpoint at which it is presented, so that the request_code alone is insufficient to retrieve a token. Only the same agent which initially tried to access the resource (and was challenged) can reuse the code. These attacks are further limited because the codes require sufficient entropy to resist guessing. They are short-lived (single use) which limits their ability to be reused should they be revealed.¶

There is certainly some risk of request_code's being leaked. The SSE and WebSocket endpoints receive the request_code in the query component of the request URI, which is more likely than a request body to be recorded in server, proxy, and client logs. The AS and AI Agents SHOULD NOT log request_code values, and operators SHOULD configure intermediaries accordingly. This is admittedly a difficult requirement to implement, and this is why additional security measures noted above are applied to them.¶

The request_code SHOULD NOT be exposed to the resource owner or to a browser; see Section 8.7.¶

8.6. Delivery of Tokens over Push Channels

Delivering the access token over an SSE stream or a WebSocket connection is as secure as delivering it in a token endpoint response, provided that the following requirements are met:¶

• The connection MUST use TLS (https or wss). Plaintext http or ws endpoints MUST NOT be advertised or used.¶

• The connection MUST be client-authenticated, with the same client authentication the token endpoint requires. A push endpoint that accepted a request_code without client authentication would deliver the token to anyone who learned the request_code.¶

• The AS MUST verify that the request_code was issued to the authenticated client.¶

• The AS MUST deliver the token at most once over a push connection. Because the AS cannot know whether a pushed message was received before a connection was lost, an AI Agent that loses the connection during delivery loses the token and must restart the flow.¶

• The AS MUST close the connection after delivering a terminal event.¶

That said - there is an important limitation with push-based tokens. A token delivered in a token endpoint response can be bound to a DPoP proof [RFC9449] presented with the request. No equivalent proof accompanies a pushed token. Tokens bound to a client certificate [RFC8705] can be delivered over a push connection established with that certificate.¶

Push connections are long-lived, and are often routed through different infrastructure. Infrastructure that terminates TLS sees the token in cleartext, and MUST NOT log or buffer frame payloads in a way that retains tokens.¶

8.7. Approval Channels and Agent-Mediated Approval

As noted at the top of this section - a key goal of the AAuth flow is that it does not require trust in the AI Agent.¶

There is one part of the flow where this is not exactly true - the web approval feature. With this feature, the AS sends the AI Agent a URL that it can use to launch a browser for the user to gain approval. A malicious AI Agent could do any number of things - it could launch the browser and use remote-control techniques to click "approve". Or, it could fetch the contents itself, and launch a browser to a fake page which presents misleading information.¶

These attacks are partly mitigated by good security practices on AI Agent usage on user desktops. A user that grants permission for an AI Agent to control its browser - with cached session tokens, cookies, and so on - is exposing themselves to a lot of risk. If the user has not allowed an AI Agent to control its browser, many of the worst attacks are removed. That said, if the AI Agent doesn't possess user's credentials to log into the AS, the AI Agent will not be able to perform the attack without the user manually entering credentials. Modern web security features, such as passcodes and password managers protect against the malicious AI Agent from taking the use to a fraudulent site. However, if the AI agent has browser controls, it could await user password entry and then auto-click on approval.¶

If the AI Agent doesn't have browser control, but only launches browser tabs, could attempt to launch the user to a malicious AS approval page. However, that AS would not be able to create tokens that will be accepted by the RS, limiting the efficacy of this attack.¶

The best protections against malicious AI Agents happen by keeping the AI Agent out of the loop entirely. This works with an AS that has an easy way to reach the user - push notifications and SMS being ideal. However, we anticipate many cases where the AS has no easy and quick way to reach the user, in which case the web approval flow will be used.¶

There are also good practices the AS can follow in the approval page to further limit risks:¶

1. Approval MUST require an explicit user action, MUST be protected against cross-site request forgery, and MUST NOT be possible through a GET request. The page MUST NOT be embeddable in a frame (for example, through a Content Security Policy of frame-ancestors 'none').¶

2. The page MUST display the client's registered name, the resource server, the reason, and the description of each scope, taken from the validated Scope Challenge and the AS's own records, and MUST NOT display text supplied by the AI Agent.¶

3. For highly secure operations, the page SHOULD require the user to re-authenticate with their credentials¶

8.8. Rate Limiting and Resource Exhaustion

Because this specification makes use of polling, the AS needs to take steps to make sure it doesnt subject itself to a self-inflicted DoS attack. But more importantly, it needs to make sure it doesnt generate a flood of approvals to the human user.¶

The AS SHOULD rate-limit polling and push connections per client, returning 429 as described in Section 5.7. It SHOULD limit the number of simultaneous push connections per client and per request_code.¶

Validation of a Scope Challenge may cause the AS to fetch an RS's metadata and JWK Set. The AS SHOULD cache these, and SHOULD rate-limit re-fetches triggered by unrecognized kid values, so that an AI Agent cannot cause the AS to make unbounded outbound requests.¶

To avoid flooding the user, the AS MUST limit the number of outstanding approval requests per combination of client (the AI Agent) and per resource owner (the user). The jti of the Scope Challenge ensures that each challenge can create at most one request.¶

8.9. Scope Descriptions

Scope descriptions are an essential part of the security of the solution. They are consumed by humans - or AI Agents operating on their behalf. This means that they need to contain sufficient explanatory text to allow either of those actors to make a good decision.¶

In addition, because they are fairly public, they shouldn't expose any sensitive information about the RS behavior.¶

8.10. Elevated Tokens

Just because a user approves an action an AI agent takes once, does not mean they would approve further actions which involve the same set of scopes.¶

For example, take again our use case of a dinner reservation. If the an AI Agent is trying to book a dinner for a user, and requires a "write" scope to do so, the user might approve that operation. Later on, the AI Agent might decide to modify the dinner, reducing the number of guests from 5 to 1. This is something the user might not approve, but the AI could do so with the same token scope ("write") it obtained previously.¶

As a result, the efficacy of the AAuth flow relies on the tokens being short-lived - generally long enough for the AI Agent to hit a number of API endpoints in a row to achieve a specified operation, but not longer.¶

The exact amount of time for the lifetime of the token is somewhat dependent on the resource server and what APIs it exposes. As a general rule of thumb, 10 seconds to a minute is a reasonable amount of time.¶

OPEN ISSUE - Even better security can be achieved if the AS is able to issue tokens which are bound to the specific operation associated with the reason phrase. Should we enhance the challenge to include API endpoints so that the AS can construct a token that actually specifies the specific API endpoints and values? Or is this too complicated? It will result in massively large tokens.¶

For similar reasons, an AS compliant to this specification SHOULD NOT issue refresh tokens.¶

9.1. OAuth URI Registration

This specification registers the following value in the "OAuth URI" sub-registry of the "OAuth Parameters" registry:¶

• URN: urn:ietf:params:oauth:grant-type:agent_authorization¶

• Common Name: Agent Authorization Grant Type¶

• Change Controller: IETF¶

• Specification Document: this document¶

9.2. OAuth Parameters Registration

This specification registers the following values in the "OAuth Parameters" registry established by [RFC6749]:¶

• Parameter name: scope_challenge; Parameter usage location: agent authorization request; Change controller: IETF; Specification document: Section 5.3 of this document.¶

• Parameter name: timeout; Parameter usage location: agent authorization request; Change controller: IETF; Specification document: Section 5.3.1 of this document.¶

• Parameter name: request_code; Parameter usage location: token request; Change controller: IETF; Specification document: Section 5.6.1 of this document.¶

9.3. OAuth Extensions Error Registration

This specification registers the following value in the "OAuth Extensions Error" registry established by [RFC6749]:¶

• Error name: invalid_scope_challenge¶

• Error usage location: agent authorization endpoint error response¶

• Related protocol extension: Agent Authorization Grant¶

• Change controller: IETF¶

• Specification document: Section 5.7 of this document¶

9.4. OAuth Authorization Server Metadata Registration

This specification registers the following value in the "OAuth Authorization Server Metadata" registry established by [RFC8414]:¶

• Metadata name: agent_authorization_endpoint¶

• Metadata description: URL of the agent authorization endpoint¶

• Change controller: IETF¶

• Specification document: Section 6.1 of this document¶

9.5. OAuth Protected Resource Metadata Registration

This specification registers the following value in the "OAuth Protected Resource Metadata" registry established by [RFC9728]:¶

• Metadata name: scope_descriptions_uri¶

• Metadata description: URL of the resource server's Scope Descriptions Document¶

• Change controller: IETF¶

• Specification document: Section 6.2 of this document¶

9.6. Media Type Registration

This specification registers the application/scope-challenge+jwt media type in the "Media Types" registry, for use as the typ header parameter value scope-challenge+jwt of a Scope Challenge (Section 5.2.1). The registration follows the template of [RFC7519] for application/jwt, with the security considerations of Section 8.3.¶

9.7. WebSocket Subprotocol Registration

This specification registers the following value in the "WebSocket Subprotocol Name" registry established by [RFC6455]:¶

• Subprotocol Identifier: aauth.agent-flow¶

• Subprotocol Common Name: AAuth Agent Authorization Flow¶

• Subprotocol Definition: Section 5.6.3 of this document¶

9.8. Well-Defined Scope

There is no IANA registry for OAuth scope values. The ai-agent-minimal scope is defined by this specification (Section 5.1) and requires no registration.¶

11.1. Normative References

[HTML]

WHATWG, "HTML Living Standard - Server-sent events", n.d., <https://html.spec.whatwg.org/multipage/server-sent-events.html>.

[I-D.bhutton-json-schema]

Wright, A., Andrews, H. H., Hutton, B., and G. Dennis, "JSON Schema: A Media Type for Describing JSON Documents", Work in Progress, Internet-Draft, draft-bhutton-json-schema-01, 10 June 2022, <https://datatracker.ietf.org/doc/html/draft-bhutton-json-schema-01>.

[RFC2119]

Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, <https://www.rfc-editor.org/rfc/rfc2119>.

[RFC5646]

Phillips, A., Ed. and M. Davis, Ed., "Tags for Identifying Languages", BCP 47, RFC 5646, DOI 10.17487/RFC5646, September 2009, <https://www.rfc-editor.org/rfc/rfc5646>.

[RFC6455]

Fette, I. and A. Melnikov, "The WebSocket Protocol", RFC 6455, DOI 10.17487/RFC6455, December 2011, <https://www.rfc-editor.org/rfc/rfc6455>.

[RFC6585]

Nottingham, M. and R. Fielding, "Additional HTTP Status Codes", RFC 6585, DOI 10.17487/RFC6585, April 2012, <https://www.rfc-editor.org/rfc/rfc6585>.

[RFC6749]

Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", RFC 6749, DOI 10.17487/RFC6749, October 2012, <https://www.rfc-editor.org/rfc/rfc6749>.

[RFC6750]

Jones, M. and D. Hardt, "The OAuth 2.0 Authorization Framework: Bearer Token Usage", RFC 6750, DOI 10.17487/RFC6750, October 2012, <https://www.rfc-editor.org/rfc/rfc6750>.

[RFC7515]

Jones, M., Bradley, J., and N. Sakimura, "JSON Web Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, May 2015, <https://www.rfc-editor.org/rfc/rfc7515>.

[RFC7517]

Jones, M., "JSON Web Key (JWK)", RFC 7517, DOI 10.17487/RFC7517, May 2015, <https://www.rfc-editor.org/rfc/rfc7517>.

[RFC7519]

Jones, M., Bradley, J., and N. Sakimura, "JSON Web Token (JWT)", RFC 7519, DOI 10.17487/RFC7519, May 2015, <https://www.rfc-editor.org/rfc/rfc7519>.

[RFC8174]

Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017, <https://www.rfc-editor.org/rfc/rfc8174>.

[RFC8259]

Bray, T., Ed., "The JavaScript Object Notation (JSON) Data Interchange Format", STD 90, RFC 8259, DOI 10.17487/RFC8259, December 2017, <https://www.rfc-editor.org/rfc/rfc8259>.

[RFC8414]

Jones, M., Sakimura, N., and J. Bradley, "OAuth 2.0 Authorization Server Metadata", RFC 8414, DOI 10.17487/RFC8414, June 2018, <https://www.rfc-editor.org/rfc/rfc8414>.

[RFC8628]

Denniss, W., Bradley, J., Jones, M., and H. Tschofenig, "OAuth 2.0 Device Authorization Grant", RFC 8628, DOI 10.17487/RFC8628, August 2019, <https://www.rfc-editor.org/rfc/rfc8628>.

[RFC8725]

Sheffer, Y., Hardt, D., and M. Jones, "JSON Web Token Best Current Practices", BCP 225, RFC 8725, DOI 10.17487/RFC8725, February 2020, <https://www.rfc-editor.org/rfc/rfc8725>.

[RFC9110]

Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, Ed., "HTTP Semantics", STD 97, RFC 9110, DOI 10.17487/RFC9110, June 2022, <https://www.rfc-editor.org/rfc/rfc9110>.

[RFC9728]

Jones, M.B., Hunt, P., and A. Parecki, "OAuth 2.0 Protected Resource Metadata", RFC 9728, DOI 10.17487/RFC9728, April 2025, <https://www.rfc-editor.org/rfc/rfc9728>.

11.2. Informative References

[I-D.hardt-oauth-aauth-protocol]

Hardt, D., "AAuth Protocol", Work in Progress, Internet-Draft, draft-hardt-oauth-aauth-protocol-11, 25 September 2026, <https://datatracker.ietf.org/doc/html/draft-hardt-oauth-aauth-protocol-11>.

[I-D.ietf-oauth-v2-1]

Hardt, D., Parecki, A., and T. Lodderstedt, "The OAuth 2.1 Authorization Framework", Work in Progress, Internet-Draft, draft-ietf-oauth-v2-1-17, 30 October 2026, <https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-17>.

[I-D.ietf-webbotauth-httpsig-protocol]

Meunier, T. and S. Major, "HTTP Message Signatures for automated traffic", Work in Progress, Internet-Draft, draft-ietf-webbotauth-httpsig-protocol-01, 29 October 2026, <https://datatracker.ietf.org/doc/html/draft-ietf-webbotauth-httpsig-protocol-01>.

[I-D.ietf-wimse-arch]

Salowey, J. A., Rosomakho, Y., and H. Tschofenig, "Workload Identity in a Multi System Environment (WIMSE) Architecture", Work in Progress, Internet-Draft, draft-ietf-wimse-arch-08, 6 July 2026, <https://datatracker.ietf.org/doc/html/draft-ietf-wimse-arch-08>.

[I-D.ietf-wimse-workload-creds]

Campbell, B., Salowey, J. A., Schwenkschuster, A., Sheffer, Y., and Y. Rosomakho, "WIMSE Workload Credentials", Work in Progress, Internet-Draft, draft-ietf-wimse-workload-creds-03, 30 October 2026, <https://datatracker.ietf.org/doc/html/draft-ietf-wimse-workload-creds-03>.

[I-D.ietf-wimse-wpt]

Campbell, B. and A. Schwenkschuster, "WIMSE Workload Proof Token", Work in Progress, Internet-Draft, draft-ietf-wimse-wpt-02, 27 August 2026, <https://datatracker.ietf.org/doc/html/draft-ietf-wimse-wpt-02>.

[OIDC]

Sakimura, N., Bradley, J., Jones, M., de Medeiros, B., and C. Mortimore, "OpenID Connect Core 1.0 incorporating errata set 2", December 2023, <https://openid.net/specs/openid-connect-core-1_0.html>.

[RFC4647]

Phillips, A., Ed. and M. Davis, Ed., "Matching of Language Tags", BCP 47, RFC 4647, DOI 10.17487/RFC4647, September 2006, <https://www.rfc-editor.org/rfc/rfc4647>.

[RFC7591]

Richer, J., Ed., Jones, M., Bradley, J., Machulak, M., and P. Hunt, "OAuth 2.0 Dynamic Client Registration Protocol", RFC 7591, DOI 10.17487/RFC7591, July 2015, <https://www.rfc-editor.org/rfc/rfc7591>.

[RFC7662]

Richer, J., Ed., "OAuth 2.0 Token Introspection", RFC 7662, DOI 10.17487/RFC7662, October 2015, <https://www.rfc-editor.org/rfc/rfc7662>.

[RFC8693]

Jones, M., Nadalin, A., Campbell, B., Ed., Bradley, J., and C. Mortimore, "OAuth 2.0 Token Exchange", RFC 8693, DOI 10.17487/RFC8693, January 2020, <https://www.rfc-editor.org/rfc/rfc8693>.

[RFC8705]

Campbell, B., Bradley, J., Sakimura, N., and T. Lodderstedt, "OAuth 2.0 Mutual-TLS Client Authentication and Certificate-Bound Access Tokens", RFC 8705, DOI 10.17487/RFC8705, February 2020, <https://www.rfc-editor.org/rfc/rfc8705>.

[RFC9068]

Bertocci, V., "JSON Web Token (JWT) Profile for OAuth 2.0 Access Tokens", RFC 9068, DOI 10.17487/RFC9068, October 2021, <https://www.rfc-editor.org/rfc/rfc9068>.

[RFC9421]

Backman, A., Ed., Richer, J., Ed., and M. Sporny, "HTTP Message Signatures", RFC 9421, DOI 10.17487/RFC9421, February 2024, <https://www.rfc-editor.org/rfc/rfc9421>.

[RFC9449]

Fett, D., Campbell, B., Bradley, J., Lodderstedt, T., Jones, M., and D. Waite, "OAuth 2.0 Demonstrating Proof of Possession (DPoP)", RFC 9449, DOI 10.17487/RFC9449, September 2023, <https://www.rfc-editor.org/rfc/rfc9449>.

[RFC9470]

Bertocci, V. and B. Campbell, "OAuth 2.0 Step Up Authentication Challenge Protocol", RFC 9470, DOI 10.17487/RFC9470, September 2023, <https://www.rfc-editor.org/rfc/rfc9470>.

[RFC9700]

Lodderstedt, T., Bradley, J., Labunets, A., and D. Fett, "Best Current Practice for OAuth 2.0 Security", BCP 240, RFC 9700, DOI 10.17487/RFC9700, January 2025, <https://www.rfc-editor.org/rfc/rfc9700>.

[W3C-AgentId]

"Agent Identity Registry Protocol Community Group", n.d., <https://www.w3.org/groups/cg/agent-identity/>.

A.1. Format

The document is a JSON object [RFC8259], served with a media type of application/json over HTTPS. The RS SHOULD serve it with caching directives that allow the AS to cache it. Its members are:¶

default_locale:

OPTIONAL. A language tag [RFC5646] identifying the language of the top-level title and description of each scope. If absent, that language is unspecified.¶

scope_descriptions:

REQUIRED. An object whose member names are scope values and whose member values are Scope Description objects.¶

A Scope Description object has the following members:¶

title:

REQUIRED. A short label for the scope, suitable for use as a heading or as a single line in a list. At most 100 characters.¶

description:

REQUIRED. One or two sentences describing what a client holding this scope can do, in terms the resource owner can act on. At most 500 characters.¶

risk:

OPTIONAL. The RS's assessment of the risk of granting the scope: one of low, medium, or high. An AS MAY use this to adjust how prominently it presents the scope, or to inform an automated approval policy.¶

localizations:

OPTIONAL. An object whose member names are language tags [RFC5646] and whose member values are objects containing a title and a description in that language, subject to the same constraints as the top-level members.¶

Unrecognized members MUST be ignored, to allow for extension.¶

When presenting a scope, the AS selects the localization that best matches the resource owner's language preferences - for example, by applying the lookup algorithm of [RFC4647] to the member names of localizations - and falls back to the top-level title and description if none matches. The AS MUST render all of these values as plain text.¶

A.2. Example

{
  "default_locale": "en",
  "scope_descriptions": {
    "urn:example:reservations.read": {
      "title": "View your reservations",
      "description": "Lets the agent see your upcoming and past
                      restaurant reservations.",
      "risk": "low",
      "localizations": {
        "de": {
          "title": "Ihre Reservierungen anzeigen",
          "description": "Erlaubt dem Agenten, Ihre vergangenen
                          und kommenden Restaurantreservierungen
                          einzusehen."
        }
      }
    },
    "urn:example:reservations.write": {
      "title": "Make and change reservations",
      "description": "Lets the agent book, change, and cancel
                      restaurant reservations on your behalf.",
      "risk": "high"
    }
  }
}

A.3. JSON Schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "AAuth Scope Descriptions Document",
  "type": "object",
  "required": ["scope_descriptions"],
  "properties": {
    "default_locale": { "$ref": "#/$defs/languageTag" },
    "scope_descriptions": {
      "type": "object",
      "minProperties": 1,
      "additionalProperties": { "$ref": "#/$defs/scopeDescription" }
    }
  },
  "$defs": {
    "languageTag": {
      "type": "string",
      "description": "A language tag as defined by RFC 5646",
      "pattern": "^[A-Za-z]{2,8}(-[A-Za-z0-9]{1,8})*$"
    },
    "title": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100
    },
    "description": {
      "type": "string",
      "minLength": 1,
      "maxLength": 500
    },
    "localizedText": {
      "type": "object",
      "required": ["title", "description"],
      "properties": {
        "title": { "$ref": "#/$defs/title" },
        "description": { "$ref": "#/$defs/description" }
      }
    },
    "scopeDescription": {
      "type": "object",
      "required": ["title", "description"],
      "properties": {
        "title": { "$ref": "#/$defs/title" },
        "description": { "$ref": "#/$defs/description" },
        "risk": {
          "type": "string",
          "enum": ["low", "medium", "high"]
        },
        "localizations": {
          "type": "object",
          "propertyNames": { "$ref": "#/$defs/languageTag" },
          "additionalProperties": {
            "$ref": "#/$defs/localizedText"
          }
        }
      }
    }
  }
}