OAuth 2.0 RAR Metadata and Error Signaling
draft-zehavi-oauth-rar-metadata-04
This document is an Internet-Draft (I-D).
Anyone may submit an I-D to the IETF.
This I-D is not endorsed by the IETF and has no formal standing in the
IETF standards process.
| Document | Type | Active Internet-Draft (individual) | |
|---|---|---|---|
| Author | Yaron Zehavi | ||
| Last updated | 2026-06-14 | ||
| RFC stream | (None) | ||
| Intended RFC status | (None) | ||
| Formats | |||
| Stream | Stream state | (No stream defined) | |
| Consensus boilerplate | Unknown | ||
| RFC Editor Note | (None) | ||
| IESG | IESG state | I-D Exists | |
| Telechat date | (None) | ||
| Responsible AD | (None) | ||
| Send notices to | (None) |
draft-zehavi-oauth-rar-metadata-04
Web Authorization Protocol Y. Zehavi
Internet-Draft Raiffeisen Bank International
Intended status: Standards Track 14 June 2026
Expires: 16 December 2026
OAuth 2.0 RAR Metadata and Error Signaling
draft-zehavi-oauth-rar-metadata-04
Abstract
OAuth 2.0 Rich Authorization Requests (RAR) [RFC9396] standardizes
the exchange and processing of authorization details but does not
define metadata for describing authorization details types.
This document addresses a practical interoperability challenge
regarding authorization details type metadata, allowing clients to
dynamically discover metadata instead of relying on out-of-band
agreements. It also standardizes error signaling for cases where
insufficient authorization details are provided, and offers
structured remediation mechanisms.
About This Document
This note is to be removed before publishing as an RFC.
The latest revision of this draft can be found at https://yaron-
zehavi.github.io/oauth-rich-authorization-requests-metadata/draft-
zehavi-oauth-rar-metadata.html. Status information for this document
may be found at https://datatracker.ietf.org/doc/draft-zehavi-oauth-
rar-metadata/.
Discussion of this document takes place on the Web Authorization
Protocol Working Group mailing list (mailto:oauth@ietf.org), which is
archived at https://mailarchive.ietf.org/arch/browse/oauth/.
Subscribe at https://www.ietf.org/mailman/listinfo/oauth/.
Source for this draft and an issue tracker can be found at
https://github.com/yaron-zehavi/oauth-rich-authorization-requests-
metadata.
Status of This Memo
This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79.
Zehavi Expires 16 December 2026 [Page 1]
Internet-Draft OAuth 2.0 RAR Metadata and Error Signali June 2026
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 16 December 2026.
Copyright Notice
Copyright (c) 2026 IETF Trust and the persons identified as the
document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents (https://trustee.ietf.org/
license-info) in effect on the date of publication of this document.
Please review these documents carefully, as they describe your rights
and restrictions with respect to this document. Code Components
extracted from this document must include Revised BSD License text as
described in Section 4.e of the Trust Legal Provisions and are
provided without warranty as described in the Revised BSD License.
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3
2. Conventions and Definitions . . . . . . . . . . . . . . . . . 4
3. Protocol Overview . . . . . . . . . . . . . . . . . . . . . . 4
3.1. Client remediates using metadata of required authorization
details types . . . . . . . . . . . . . . . . . . . . . . 5
3.2. Client remediates using actionable authorization details
objects provided by resource server . . . . . . . . . . . 7
4. Authorization Details Types Metadata Endpoint . . . . . . . . 9
4.1. Authorization Details Types Metadata Endpoint Response . 9
5. Resource Server Error Signaling of insufficient
authorization_details . . . . . . . . . . . . . . . . . . 10
5.1. RECOMMENDED authorization_details_types_required in
response body . . . . . . . . . . . . . . . . . . . . . . 11
5.1.1. Required types expression syntax . . . . . . . . . . 11
5.1.2. Required types expression examples . . . . . . . . . 12
5.2. OPTIONAL actionable authorization_details in response
body . . . . . . . . . . . . . . . . . . . . . . . . . . 13
6. Handling large RAR objects when issuing access tokens . . . . 14
7. Processing Rules . . . . . . . . . . . . . . . . . . . . . . 14
7.1. Client Processing Rules . . . . . . . . . . . . . . . . . 15
Zehavi Expires 16 December 2026 [Page 2]
Internet-Draft OAuth 2.0 RAR Metadata and Error Signali June 2026
7.2. Resource Server Processing Rules . . . . . . . . . . . . 15
8. Security Considerations . . . . . . . . . . . . . . . . . . . 16
8.1. Cacheability and Intermediaries . . . . . . . . . . . . . 16
8.2. Confidentiality of resource server provided
authorization_details . . . . . . . . . . . . . . . . . . 16
9. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 16
9.1. OAuth 2.0 WWW-Authenticate Error Code Registry . . . . . 16
9.2. OAuth Authorization Server Metadata Registry . . . . . . 17
10. Normative References . . . . . . . . . . . . . . . . . . . . 17
Appendix A. Examples . . . . . . . . . . . . . . . . . . . . . . 18
A.1. Authorization Server Metadata Examples . . . . . . . . . 18
A.1.1. Example authorization_details_types_metadata_endpoint
response with Payment Initiation . . . . . . . . . . 18
A.1.2. Example authorization_details_types_metadata_endpoint
response for the Norwegian Health Sector (HelseID) . 20
A.2. Resource Server authorization_details_types_required
Response Examples . . . . . . . . . . . . . . . . . . . . 25
A.2.1. Example Resource server
authorization_details_types_required response from
payments resource . . . . . . . . . . . . . . . . . . 26
A.2.2. Example Resource server
authorization_details_types_required response from the
Norwegian Health Sector (HelseID) . . . . . . . . . . 26
A.3. Payment initiation with RAR error signaling . . . . . . . 26
A.3.1. Client initiates API request . . . . . . . . . . . . 26
A.3.2. Resource server signals
insufficient_authorization_details with actionable RAR
object . . . . . . . . . . . . . . . . . . . . . . . 27
A.3.3. Client initiates OAuth flow using the provided
authorization_details object . . . . . . . . . . . . 28
A.3.4. Client re-attempts API request . . . . . . . . . . . 28
A.3.5. Resource server authorizes the request . . . . . . . 29
Appendix B. Document History . . . . . . . . . . . . . . . . . . 29
Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 30
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 30
1. Introduction
OAuth 2.0 Rich Authorization Requests (RAR) [RFC9396] allows OAuth
clients to request detailed and structured authorization, enabling
advanced authorization models across domains such as banking and
healthcare.
However, RAR [RFC9396] does not specify how clients discover metadata
describing valid authorization details objects. Such metadata and
documentation are obtained out-of-band.
This document defines:
Zehavi Expires 16 December 2026 [Page 3]
Internet-Draft OAuth 2.0 RAR Metadata and Error Signali June 2026
* A new authorization server endpoint:
authorization_details_types_metadata_endpoint, providing
authorization details type metadata, including documentation and
JSON Schema definitions [JSON.Schema].
* A new normative OAuth 2.0 WWW-Authenticate Error Code, for
resource servers to indicate insufficient_authorization_details as
the cause of the error, as well as a RECOMMENDED response body
specifying required authorization details types to satisfy the
resource's requirements.
* An OPTIONAL response body attribute that MAY accompany the
insufficient_authorization_details error, providing an informative
and actionable authorization details object. This object can be
used directly in a follow-up OAuth request.
* RECOMMENDED handling of large RAR [RFC9396] authorization details
objects when issuing JWT access tokens, to avoid failures due to
token sizes exceeding header size restrictions.
Providing actionable authorization details objects in the resource
server's error response enables:
* Simplification for clients who can directly remediate without
learning to construct valid authorization details objects.
* Support for ephemeral, interaction-specific attributes from the
resource server, such as a risk profile or an internal interaction
identifier, guiding authorization servers on required
authentication strength and consent flows.
2. Conventions and Definitions
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
"OPTIONAL" in this document are to be interpreted as described in
BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all
capitals, as shown here.
3. Protocol Overview
There are two main proposed flows:
* Client remediates using *metadata of required authorization
details types*.
* Client remediates using *actionable authorization details objects*
provided by resource server.
Zehavi Expires 16 December 2026 [Page 4]
Internet-Draft OAuth 2.0 RAR Metadata and Error Signali June 2026
3.1. Client remediates using metadata of required authorization details
types
Zehavi Expires 16 December 2026 [Page 5]
Internet-Draft OAuth 2.0 RAR Metadata and Error Signali June 2026
+---------------------+
+----------+ (B) API Request | |
| |---------------------->| Resource |
(A) User +---| | | Server |
Starts| | |<----------------------| |
Flow +-->| | (C) 403 Forbidden +---------------------+
| | WWW-Authenticate: Bearer
| | error="insufficient_authorization_details"
| | +
| | HTTP body specifies
| | required authorization_details
| | :
| | +---------------------+
| | RAR Types | Authorization |
| | (D) Metadata Request | Server |
| |---------------------->|+-------------------+|
| | || RAR Types ||
| |<----------------------|| Metadata Endpoint ||
| | (E) Metadata Response |+-------------------+|
| | : | |
| | (F) Construct RAR | |
| | Using Metadata | |
| | : | |
| | (G) Authorization | |
| | Request + RAR | |
| |---------------------->|+-------------------+|
| | || Authorization ||
| |<----------------------|| Endpoint ||
| | (H) Authorization Code|| ||
| | : |+-------------------+|
| | : | |
| | (I) Token Request |+-------------------+|
| |---------------------->|| ||
| | || Token Endpoint ||
| |<----------------------|| ||
| | (J) Access Token |+-------------------+|
| | : +---------------------+
| | :
| | (K) API Call with
| | Access Token +---------------------+
| |---------------------->| |
| | | Resource Server |
| |<----------------------| |
| | (L) 200 OK + Resource +---------------------+
| |
+----------+
Zehavi Expires 16 December 2026 [Page 6]
Internet-Draft OAuth 2.0 RAR Metadata and Error Signali June 2026
Figure: Client remediates using metadata of required authorization
details types
* (A) The user starts the flow.
* (B) The client calls an API with an access token.
* (C) Resource server returns HTTP 403 Forbidden, including a WWW-
Authenticate header with error code
insufficient_authorization_details and in the response body
specifies required authorization details types.
* (D-E) The client consumes authorization details types metadata
from authorization server's
authorization_details_types_metadata_endpoint.
* (F-G) The client constructs valid authorization details objects
and makes an authorization request using RAR [RFC9396].
* (H) Authorization server returns authorization code.
* (I-J) The client exchanges authorization code for access token.
* (K) The client makes an API request with the (RAR) access token.
* (L) Resource server validates access token and returns successful
response.
3.2. Client remediates using actionable authorization details objects
provided by resource server
Zehavi Expires 16 December 2026 [Page 7]
Internet-Draft OAuth 2.0 RAR Metadata and Error Signali June 2026
+--------------------+
+----------+ (B) API Request | |
| |---------------------->| Resource |
(A) User +---| | | Server |
Starts| | |<----------------------| |
Flow +-->| Client | (C) 403 Forbidden +--------------------+
| | WWW-Authenticate: Bearer
| | error="insufficient_authorization_details"
| | +
| | HTTP body provides authorization_details
| | :
| | : +--------------------+
| | : | Authorization |
| | (D) Authorization | Server |
| | Request + RAR |+------------------+|
| |---------------------->|| ||
| | || Authorization ||
| |<----------------------|| Endpoint ||
| | (E) Authorization Code|| ||
| | : |+------------------+|
| | : | |
| | (F) Token Request |+------------------+|
| |---------------------->|| ||
| | || Token Endpoint ||
| |<----------------------|| ||
| | (G) Access Token |+------------------+|
| | : +--------------------+
| | :
| | :
| | (H) Retry API Call +--------------------+
| | with Token | |
| |---------------------->| Resource |
| | | Server |
| |<----------------------| |
| | (I) 200 OK + Resource +--------------------+
| |
+----------+
Figure: Client remediates using actionable authorization details
objects provided by resource server
* (A) The user starts the flow.
* (B) The client calls an API with an access token.
Zehavi Expires 16 December 2026 [Page 8]
Internet-Draft OAuth 2.0 RAR Metadata and Error Signali June 2026
* (C) Resource server returns HTTP 403 Forbidden, including a WWW-
Authenticate header with error code
insufficient_authorization_details and in the response body
includes the *required authorization details objects*.
* (D) The client uses the obtained authorization details objects in
a new OAuth + RAR [RFC9396] request.
* (E) Authorization server returns authorization code.
* (F-G) The client exchanges authorization code for access token.
* (H) The client makes an API request with the (RAR) access token.
* (I) Resource server validates access token and returns successful
response.
4. Authorization Details Types Metadata Endpoint
The following authorization server metadata [RFC8414] parameter is
introduced to indicate the server's support for Authorization Details
Types Metadata:
"authorization_details_types_metadata_endpoint": OPTIONAL. The URL
of the Authorization Details Types Metadata endpoint.
4.1. Authorization Details Types Metadata Endpoint Response
The Authorization Details Types Metadata endpoint is called with HTTP
GET and responds with Content-Type application/json and a JSON object
whose members are authorization details type identifiers.
Each member value is an object describing a single authorization
details type.
{
"type": {
"version": "...",
"description": "...",
"documentation_uri": "...",
"schema": { },
"schema_uri": "...",
"examples": [ ]
}
}
Attribute definition:
Zehavi Expires 16 December 2026 [Page 9]
Internet-Draft OAuth 2.0 RAR Metadata and Error Signali June 2026
"version": OPTIONAL. String identifying the version of the
authorization details type definition. The value is informational
and does not imply semantic version negotiation.
"description": OPTIONAL. String containing a description of the
authorization details type. Clients MUST NOT rely on this value
for authorization or validation decisions.
"documentation_uri": OPTIONAL. URI referencing external
documentation describing the authorization details type.
"schema": The schema attribute contains a JSON Schema document
[JSON.Schema] that describes a single authorization details
object. The schema MUST validate exactly one authorization
details object and MUST restrict the type attribute to the
corresponding authorization details type identifier. This
attribute is REQUIRED unless schema_uri is specified. If present,
schema_uri MUST NOT be included.
"schema_uri": The schema_uri attribute is an absolute URI, as
defined by RFC 3986 [RFC3986], referencing a JSON Schema document
describing a single authorization details object. The referenced
schema MUST satisfy the same requirements as the schema attribute.
This attribute is REQUIRED unless schema is specified. If this
attribute is present, schema MUST NOT be present.
"examples": OPTIONAL. An array of example authorization details
objects. Examples are non-normative.
See Examples Appendix A.1 for non-normative response example.
5. Resource Server Error Signaling of insufficient
authorization_details
This document defines the Bearer authentication error code
insufficient_authorization_details for use in the WWW-Authenticate
header field as defined by [RFC6750]. Resource servers SHOULD return
insufficient_authorization_details to signal that access is denied
due to missing or insufficient authorization details. The
insufficient_authorization_details error is intended in cases where
the access token is otherwise valid, but the authorization details
associated with the token do not satisfy the resource's requirements.
The insufficient_authorization_details error MUST NOT be used when
the access token is missing, expired, malformed, or otherwise
invalid. Existing Bearer authentication error codes are used for
those cases.
Example HTTP response:
Zehavi Expires 16 December 2026 [Page 10]
Internet-Draft OAuth 2.0 RAR Metadata and Error Signali June 2026
HTTP/1.1 403 Forbidden
WWW-Authenticate: Bearer error="insufficient_authorization_details"
5.1. RECOMMENDED authorization_details_types_required in response body
It is RECOMMENDED that resource servers return, alongside the
insufficient_authorization_details error, an HTTP body of Content-
Type application/json containing the new attribute:
authorization_details_types_required. This attribute specifies the
required authorization details *types* satisfying resource's RAR
[RFC9396] requirements.
"authorization_details_types_required": RECOMMENDED. A JSON object
that conforms to the syntax described in Section 5.1.1 for a
_required types expression_.
Note: It is RECOMMENDED that _authorization_details_types_required_
specifies ALL acceptable authorization details types combinations,
from ALL supported authorization servers.
Example resource server response with RECOMMENDED
authorization_details_types_required:
HTTP/1.1 403 Forbidden
WWW-Authenticate: Bearer error="insufficient_authorization_details"
Content-Type: application/json
{
"authorization_details_types_required": {
"oneOf": ["payment_initiation", "payment_approval",
"beneficiary_designation"]
}
}
5.1.1. Required types expression syntax
The following JSON syntax defines a *required types expression* that
describes permitted combinations of required _authorization_details_
types. This expression allows selection operators (oneOf, allOf) and
boolean composition (and, or) to be combined in a predictable manner.
A *required types expression* is a JSON object that MUST contain
*exactly* one of the following attributes:
* and
* or
Zehavi Expires 16 December 2026 [Page 11]
Internet-Draft OAuth 2.0 RAR Metadata and Error Signali June 2026
* oneOf
* allOf
Attribute definition:
"and": OPTIONAL. A non-empty JSON array of _required types
expressions_. When *and* is specified, the expression is satisfied
if *all* contained expressions are satisfied.
"or": OPTIONAL. A non-empty JSON array of _required types
expressions_. When *or* is specified, the expression is satisfied
if *at least one* contained expression is satisfied.
"oneOf": OPTIONAL. A non-empty JSON array of strings identifying
authorization_details types. When *oneOf* is specified, the
expression is satisfied if *exactly one* of the listed types is
present.
"allOf": OPTIONAL. A non-empty JSON array of strings identifying
authorization_details types. When *allOf* is specified, the
expression is satisfied if *all* of the listed types are present.
5.1.2. Required types expression examples
5.1.2.1. Example expression using "and" operator
Specifies that the selection MUST include a and b, *and* one of c
*or* d.
{
"and": [
{ "allOf": ["a", "b"] },
{ "oneOf": ["c", "d"] }
]
}
5.1.2.2. Example expression using "or" operator
Specifies that the selection MUST include *either* c *and* d, *or*
one of a or b.
{
"or": [
{ "allOf": ["c", "d"] },
{ "oneOf": ["a", "b"] }
]
}
Zehavi Expires 16 December 2026 [Page 12]
Internet-Draft OAuth 2.0 RAR Metadata and Error Signali June 2026
5.2. OPTIONAL actionable authorization_details in response body
The resource server MAY include, in addition to or instead of the
authorization_details_types_required attribute, actionable
authorization details objects capable of satisfying the resource's
requirements.
Note:
* Resource servers SHOULD provide authorization_details objects
intended to be submitted to the authorization server that issued
the access token used for the current (failing) request. This
simplifies client and end-user interaction, by continuing with the
same authorization server previously used.
HTTP response body definition:
"authorization_details": OPTIONAL. Array of authorization details
objects, matching the format specified in RAR [RFC9396] for the
authorization_details request parameter.
"authorization_hint": RECOMMENDED. An opaque string generated by
the resource server that enables the client to select an existing
access token associated with equivalent authorization details
without understanding the semantics of the authorization details
object. Clients MUST treat this value as opaque. The value
SHOULD be stable only within the context of the same resource
server, client, subject, and authorization server. The value MUST
NOT reveal sensitive information. The resource server SHALL NOT
return this attribute when tokens resulting from the provided
authorization_details are single-use only.
Clients MAY use the provided authorization_details in a subsequent
OAuth request to obtain an access token satisfying the resource's
requirements.
Example resource server response with OPTIONAL authorization_details:
Zehavi Expires 16 December 2026 [Page 13]
Internet-Draft OAuth 2.0 RAR Metadata and Error Signali June 2026
HTTP/1.1 403 Forbidden
WWW-Authenticate: Bearer error="insufficient_authorization_details"
Content-Type: application/json
Cache-Control: no-store
{
"authorization_details_types_required": {
"oneOf": ["payment_initiation"]
},
"authorization_details": [{
"type": "payment_initiation",
"instructed_amount": {
"currency": "EUR",
"amount": "100.00"
},
"creditor_account": {
"iban": "DE02120300000000202051"
}
}],
"authorization_hint": "Yb7q3AC5d"
}
6. Handling large RAR objects when issuing access tokens
RAR [RFC9396] section 9 instructs that authorization servers MUST
provide approved RAR objects to resource servers for enforcement.
The authorization server MAY add the authorization_details attribute
to access tokens in JSON Web Token (JWT) format or to token
introspection responses.
Including large RAR objects in JWT access tokens may cause
interoperability loss due to token sizes exceeding header size
restrictions.
Authorization servers SHOULD support a configurable *maximum approved
RAR objects size threshold*. The size calculation SHOULD be based on
the UTF-8 encoded JSON serialization of the approved
authorization_details value before JWT signing or encryption. If the
size exceeds this threshold, JWT access tokens SHOULD NOT include the
authorization_details attribute; instead, the authorization server
MUST ensure that the resource server can obtain the approved
authorization details by another means, such as token introspection
[RFC7662].
7. Processing Rules
Zehavi Expires 16 December 2026 [Page 14]
Internet-Draft OAuth 2.0 RAR Metadata and Error Signali June 2026
7.1. Client Processing Rules
* When receiving an insufficient_authorization_details error, if the
response body contains an authorization_hint attribute that
matches a valid token in the client's possession, the client
SHOULD retry the failing request using the matching token.
* If the response body contains an authorization_details attribute,
the client MAY include it in a subsequent OAuth request to obtain
a token, which it MAY then use to retry the failing endpoint.
* Otherwise, the client SHOULD use the
authorization_details_types_required attribute, if provided in the
response body:
- Use the response body to understand which authorization details
types satisfy the resource's requirements.
- If the authorization server metadata contains
authorization_details_types_supported, the client MAY use it to
determine whether the authorization server supports one or more
types referenced by authorization_details_types_required.
- Fetch authorization server's
authorization_details_types_metadata_endpoint to obtain
authorization details types metadata and schemas.
- Use the embedded schema value or retrieve the JSON Schema
document from schema_uri.
* Construct authorization details conforming to the schema and
include them in a subsequent OAuth request to obtain an access
token with which the client MAY retry calling the failing
endpoint.
7.2. Resource Server Processing Rules
* Verify access tokens against required authorization details.
* When a resource server receives a JWT access token that does not
contain an authorization_details claim, and authorization details
are required for the requested resource, the resource server
SHOULD attempt to obtain the authorization details using token
introspection [RFC7662], if introspection is available.
* If authorization details are missing or insufficient, the resource
server SHALL return HTTP 403 with WWW-Authenticate: Bearer
error="insufficient_authorization_details".
Zehavi Expires 16 December 2026 [Page 15]
Internet-Draft OAuth 2.0 RAR Metadata and Error Signali June 2026
* It is RECOMMENDED to also provide an HTTP body with the
authorization_details_types_required attribute, specifying the
required authorization details types to satisfy the resource's
requirement. This attribute applies to ALL supported
authorization servers.
* Resource server MAY also provide in the HTTP body, OPTIONAL
actionable authorization_details objects, intended to be submitted
to the authorization server that issued the current access token,
which MAY be used directly for remediation in a subsequent OAuth
request.
8. Security Considerations
8.1. Cacheability and Intermediaries
HTTP 403 responses with response bodies may be cached or replayed in
unexpected contexts. Resource servers SHOULD mitigate by including
the Cache-Control: no-store response header.
8.2. Confidentiality of resource server provided authorization_details
Resource server providing actionable authorization_details SHOULD NOT
include sensitive data in those objects. This is consistent with RAR
[RFC9396] authorization_details OAuth request parameter, representing
*request* semantics.
Confidentiality-preserving authorization_details types SHOULD NOT
include sensitive data. Instead, the end-user SHOULD provide such
information when interacting with the authorization server.
Alternatively, authorization_details MAY refer to specific end-user
resources using opaque reference handles (e.g., "account_1a" instead
of using explicit IBAN).
9. IANA Considerations
9.1. OAuth 2.0 WWW-Authenticate Error Code Registry
+==================================+========+==========+=============+
|Error Code |Error |Change |Specification|
| |Usage |Controller|Document |
| |Location| | |
+==================================+========+==========+=============+
|insufficient_authorization_details|Resource|IETF |RFC XXXX, |
| |access | |Section X |
| |error | | |
| |response| | |
Zehavi Expires 16 December 2026 [Page 16]
Internet-Draft OAuth 2.0 RAR Metadata and Error Signali June 2026
+----------------------------------+--------+----------+-------------+
Table 1
9.2. OAuth Authorization Server Metadata Registry
This specification registers the following authorization server
metadata parameter in the OAuth Authorization Server Metadata
registry:
+=============================================+=============+==========+=============+
|Metadata Name |Metadata |Change |Specification|
| |Description |Controller|Document |
+=============================================+=============+==========+=============+
|authorization_details_types_metadata_endpoint|URL of the |IETF |RFC XXXX, |
| |Authorization| |Section X |
| |Details Types| | |
| |Metadata | | |
| |endpoint | | |
+---------------------------------------------+-------------+----------+-------------+
Table 2
10. Normative References
[IANA.oauth-parameters]
IANA, "OAuth Parameters",
<https://www.iana.org/assignments/oauth-parameters>.
[JSON.Schema]
Wright, Ed, A., Andrews, Ed, H., Hutton, Ed, B., and G.
Dennis, "JSON Schema: A Media Type for Describing JSON
Documents", June 2022,
<https://json-schema.org/draft/2020-12/json-schema-core>.
[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>.
[RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
Resource Identifier (URI): Generic Syntax", STD 66,
RFC 3986, DOI 10.17487/RFC3986, January 2005,
<https://www.rfc-editor.org/rfc/rfc3986>.
Zehavi Expires 16 December 2026 [Page 17]
Internet-Draft OAuth 2.0 RAR Metadata and Error Signali June 2026
[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>.
[RFC7662] Richer, J., Ed., "OAuth 2.0 Token Introspection",
RFC 7662, DOI 10.17487/RFC7662, October 2015,
<https://www.rfc-editor.org/rfc/rfc7662>.
[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>.
[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>.
[RFC9396] Lodderstedt, T., Richer, J., and B. Campbell, "OAuth 2.0
Rich Authorization Requests", RFC 9396,
DOI 10.17487/RFC9396, May 2023,
<https://www.rfc-editor.org/rfc/rfc9396>.
[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>.
Appendix A. Examples
This section provides non-normative examples of how this
specification may be used to support specific use cases.
A.1. Authorization Server Metadata Examples
A.1.1. Example authorization_details_types_metadata_endpoint response
with Payment Initiation
HTTP/1.1 200 OK
Content-Type: application/json
{
"payment_initiation": {
"version": "1.0",
"description": "Authorization to initiate a single payment from a payer account to a creditor account.",
"documentation_uri": "https://example.com/docs/payment-initiation",
"schema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
Zehavi Expires 16 December 2026 [Page 18]
Internet-Draft OAuth 2.0 RAR Metadata and Error Signali June 2026
"title": "Payment Initiation Authorization Detail",
"type": "object",
"required": [
"type",
"instructed_amount",
"creditor_account"
],
"properties": {
"type": {
"const": "payment_initiation",
"description": "Authorization details type identifier."
},
"actions": {
"type": "array",
"description": "Permitted actions for this authorization.",
"items": {
"type": "string",
"enum": ["initiate"]
},
"minItems": 1,
"uniqueItems": true
},
"instructed_amount": {
"type": "object",
"description": "Amount and currency of the payment to be initiated.",
"required": ["currency", "amount"],
"properties": {
"currency": {
"type": "string",
"description": "ISO 4217 currency code.",
"pattern": "^[A-Z]{3}$"
},
"amount": {
"type": "string",
"description": "Decimal monetary amount represented as a string.",
"pattern": "^[0-9]+(\\.[0-9]{1,2})?$"
}
}
},
"creditor_account": {
"type": "object",
"description": "Account to which the payment will be credited.",
"required": ["iban"],
"properties": {
"iban": {
"type": "string",
"description": "International Bank Account Number (IBAN).",
"pattern": "^[A-Z0-9]{15,34}$"
Zehavi Expires 16 December 2026 [Page 19]
Internet-Draft OAuth 2.0 RAR Metadata and Error Signali June 2026
}
}
},
"remittance_information": {
"type": "string",
"description": "Unstructured remittance information for the payment.",
"maxLength": 140
}
}
}
}
}
A.1.2. Example authorization_details_types_metadata_endpoint response
for the Norwegian Health Sector (HelseID)
HTTP/1.1 200 OK
Content-Type: application/json
{
"helseid_authorization": {
"version": "1.0",
"description": "Allows the OAuth client to pass organization information to HelseID.",
"documentation_uri": "https://utviklerportal.nhn.no/informasjonstjenester/helseid/bruksmoenstre-og-eksempelkode/bruk-av-helseid/docs/tekniske-mekanismer/organisasjonsnumre_enmd",
"schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"title": "Organization numbers for a multi-tenant client",
"type": "object",
"properties": {
"type": {
"type": "string",
"const": "helseid_autorization"
},
"practitioner_role": {
"type": "object",
"properties": {
"organization": {
"type": "object",
"properties": {
"identifier": {
"type": "object",
"properties": {
"system": {
"type": "string"
},
"type": {
"type": "string"
Zehavi Expires 16 December 2026 [Page 20]
Internet-Draft OAuth 2.0 RAR Metadata and Error Signali June 2026
},
"value": {
"type": "string"
}
},
"required": [
"system",
"type",
"value"
]
}
},
"required": [
"identifier"
]
}
},
"required": [
"organization"
]
}
},
"required": [
"type",
"practitioner_role"
]
}
},
"helseid_trust_framework": {
"version": "1.0",
"description": "HelseID Trust Framework Information",
"documentation_uri": "https://utviklerportal.nhn.no/informasjonstjenester/helseid/bruksmoenstre-og-eksempelkode/bruk-av-helseid/docs/tekniske-mekanismer/trust-framework",
"schema": {
"$schema": "http://json-schema.org/draft-07/schema#",
"description": "Complete Trust Framework structure",
"documentation_uri": "https://utviklerportal.nhn.no/informasjonstjenester/helseid/bruksmoenstre-og-eksempelkode/bruk-av-helseid/docs/tillitsrammeverk/profil_for_tillitsrammeverkmd",
"type": "object",
"properties": {
"type": {
"type": "string",
"const": "nhn:tillitsrammeverk:parameters"
},
"practitioner": {
"type": "object",
"properties": {
"authorization": {
"type": "object",
"properties": {
Zehavi Expires 16 December 2026 [Page 21]
Internet-Draft OAuth 2.0 RAR Metadata and Error Signali June 2026
"code": {
"type": "string"
},
"system": {
"type": "string"
}
},
"required": [
"code",
"system"
]
},
"legal_entity": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"system": {
"type": "string"
}
},
"required": [
"id",
"system"
]
},
"point_of_care": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"system": {
"type": "string"
}
},
"required": [
"id",
"system"
]
},
"department": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
Zehavi Expires 16 December 2026 [Page 22]
Internet-Draft OAuth 2.0 RAR Metadata and Error Signali June 2026
"system": {
"type": "string"
}
},
"required": [
"id",
"system"
]
}
},
"required": [
"authorization",
"legal_entity",
"point_of_care",
"department"
]
},
"care_relationship": {
"type": "object",
"properties": {
"healthcare_service": {
"type": "object",
"properties": {
"code": {
"type": "string"
},
"system": {
"type": "string"
}
},
"required": [
"code",
"system"
]
},
"purpose_of_use": {
"type": "object",
"properties": {
"code": {
"type": "string"
},
"system": {
"type": "string"
}
},
"required": [
"code",
"system"
Zehavi Expires 16 December 2026 [Page 23]
Internet-Draft OAuth 2.0 RAR Metadata and Error Signali June 2026
]
},
"purpose_of_use_details": {
"type": "object",
"properties": {
"code": {
"type": "string"
},
"system": {
"type": "string"
}
},
"required": [
"code",
"system"
]
},
"decision_ref": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"user_selected": {
"type": "boolean"
}
},
"required": [
"id",
"user_selected"
]
}
},
"required": [
"healthcare_service",
"purpose_of_use",
"purpose_of_use_details",
"decision_ref"
]
},
"patients": {
"type": "array",
"items": {
"type": "object",
"properties": {
"point_of_care": {
"type": "object",
"properties": {
Zehavi Expires 16 December 2026 [Page 24]
Internet-Draft OAuth 2.0 RAR Metadata and Error Signali June 2026
"id": {
"type": "string"
},
"system": {
"type": "string"
}
},
"required": [
"id",
"system"
]
},
"department": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"system": {
"type": "string"
}
},
"required": [
"id",
"system"
]
}
},
"required": [
"point_of_care",
"department"
]
}
}
},
"required": [
"type",
"practitioner",
"care_relationship",
"patients"
]
}
}
}
A.2. Resource Server authorization_details_types_required Response
Examples
Zehavi Expires 16 December 2026 [Page 25]
Internet-Draft OAuth 2.0 RAR Metadata and Error Signali June 2026
A.2.1. Example Resource server authorization_details_types_required
response from payments resource
HTTP/1.1 403 Forbidden
WWW-Authenticate: Bearer error="insufficient_authorization_details"
Content-Type: application/json
Cache-Control: no-store
{
"authorization_details_types_required": {
"oneOf": ["payment_initiation", "payment_approval",
"beneficiary_designation"]
}
}
A.2.2. Example Resource server authorization_details_types_required
response from the Norwegian Health Sector (HelseID)
HTTP/1.1 403 Forbidden
WWW-Authenticate: Bearer error="insufficient_authorization_details"
Content-Type: application/json
Cache-Control: no-store
{
"authorization_details_types_required": {
"allOf": ["helseid_authorization",
"nhn:tillitsrammeverk:parameters"]
}
}
A.3. Payment initiation with RAR error signaling
A.3.1. Client initiates API request
Client uses access token obtained at login to call payment initiation
API
Zehavi Expires 16 December 2026 [Page 26]
Internet-Draft OAuth 2.0 RAR Metadata and Error Signali June 2026
POST /payments HTTP/1.1
Host: resource.example.com
Content-Type: application/json
Authorization: Bearer eyj... (access token from login)
{
"type": "payment_initiation",
"locations": [
"https://resource.example.com/payments"
],
"instructed_amount": {
"currency": "EUR",
"amount": "123.50"
},
"creditor_name": "Merchant A",
"creditor_account": {
"bic": "ABCIDEFFXXX",
"iban": "DE02100100109307118603"
}
}
A.3.2. Resource server signals insufficient_authorization_details with
actionable RAR object
Resource server requires payment approval and responds with:
Zehavi Expires 16 December 2026 [Page 27]
Internet-Draft OAuth 2.0 RAR Metadata and Error Signali June 2026
HTTP/1.1 403 Forbidden
WWW-Authenticate: Bearer error="insufficient_authorization_details"
Content-Type: application/json
Cache-Control: no-store
{
"authorization_details": [{
"type": "payment_initiation",
"locations": [
"https://resource.example.com/payments"
],
"instructed_amount": {
"currency": "EUR",
"amount": "123.50"
},
"creditor_name": "Merchant A",
"creditor_account": {
"bic": "ABCIDEFFXXX",
"iban": "DE02100100109307118603"
},
"interaction_id": "f81d4fae-7dec-11d0-a765-00a0c91e6bf6",
"risk_profile": "B-71"
}
]
}
Note: the resource server has added the ephemeral attributes
interaction_id and risk_profile.
A.3.3. Client initiates OAuth flow using the provided
authorization_details object
After user approves the request, client obtains an access token
representing the approved payment
A.3.4. Client re-attempts API request
Zehavi Expires 16 December 2026 [Page 28]
Internet-Draft OAuth 2.0 RAR Metadata and Error Signali June 2026
POST /payments HTTP/1.1
Host: resource.example.com
Content-Type: application/json
Authorization: Bearer eyj... (payment approval access token)
{
"type": "payment_initiation",
"locations": [
"https://resource.example.com/payments"
],
"instructed_amount": {
"currency": "EUR",
"amount": "123.50"
},
"creditor_name": "Merchant A",
"creditor_account": {
"bic": "ABCIDEFFXXX",
"iban": "DE02100100109307118603"
}
}
A.3.5. Resource server authorizes the request
HTTP/1.1 201 Accepted
Content-Type: application/json
Cache-Control: no-store
{
"paymentId": "a81bc81b-dead-4e5d-abff-90865d1e13b1",
"status": "accepted"
}
Appendix B. Document History
-04
* Moved required authorization details types from resource metadata
to resource server's response.
* Adapted resource server processing rules to reflect error
signaling and handling of large RAR payloads.
-03
* Added authorization_hint to guide client on token selection and
updated client processing rules accordingly
Zehavi Expires 16 December 2026 [Page 29]
Internet-Draft OAuth 2.0 RAR Metadata and Error Signali June 2026
* Added security consideration on confidentiality of RS-provided
authorization_details
* Added authorization server considerations for handling large RAR
objects in JWT access tokens
-02
* Defined the required types expression
* Added Protected Resource Metadata examples
-01
* Authorization details moved to HTTP body and made OPTIONAL
* Metadata pointer from resource metadata url, full authorization
details types metadata on authorization server new endpoint
-00
* Document creation
Acknowledgments
The authors would like to thank the following individuals who
contributed ideas, feedback, and wording that helped shape the final
specification: Rune Grimstad.
Author's Address
Yaron Zehavi
Raiffeisen Bank International
Email: yaron.zehavi@rbinternational.com
Zehavi Expires 16 December 2026 [Page 30]