Internet-Draft OAuth 2.0 RAR Metadata and Error Signali February 2026
Zehavi Expires 26 August 2026 [Page]
Workgroup:
Web Authorization Protocol
Internet-Draft:
draft-zehavi-oauth-rar-metadata-02
Published:
Intended Status:
Standards Track
Expires:
Author:
Y. Zehavi
Raiffeisen Bank International

OAuth 2.0 RAR Metadata and Error Signaling

Abstract

OAuth 2.0 Rich Authorization Requests (RAR), as defined in [RFC9396], enables fine-grained authorization requests, using structured JSON objects.

While RAR [RFC9396] standardizes the exchange and processing of authorization details, it does not specify metadata describing authorization details types.

This document defines a machine-readable metadata format for authorization servers to provide authorization details type documentation including JSON Schema [JSON.Schema] definitions, as well as interoperable discovery via OAuth Resource Server Metadata [RFC9728].

It also defines a new WWW-Authenticate normative OAuth error code, insufficient_authorization_details, enabling resource servers to indicate inadequate authorization details as the cause of failure, as well as an OPTIONAL response body which MAY be returned alongside the insufficient_authorization_details error, providing an informative yet actionable authorization details object, which can be used directly in a subsequent OAuth request.

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.

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 26 August 2026.

▲

Table of Contents

1. Introduction

OAuth 2.0 Rich Authorization Requests (RAR) [RFC9396] allows OAuth clients to request structured, fine-grained authorization, which has enabled advanced authorization models across many domains, such as Banking & Healthcare.

However, RAR [RFC9396] does not specify how clients obtain metadata describing valid authorization details objects. Clients must therefore rely on out-of-band documentation or static ecosystem profiles.

This document addresses this gap by:

The OPTIONAL providing of actionable authorization details objects by resource servers enables:

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:

3.1. Client obtains metadata of required authorization details types 

                                                +---------------------+
             +----------+ (B) API Request       |                     |
             |          |---------------------->|      Resource       |
(A) User +---|          |                       |       Server        |
   Starts|   |          |<----------------------|                     |
   Flow  +-->|          | (C) 403 Forbidden     +---------------------+
             |          |     WWW-Authenticate: Bearer
             |          |     error="insufficient_authorization_details",
             |          |     resource_metadata="[resource metadata url]"
             |          |           :
             |          |        Resource       +---------------------+
             |          | (D) Metadata Request  |   Resource Server   |
             |          |---------------------->|+-------------------+|
             |          |                       || Resource Metadata ||
             |  Client  |<----------------------||    Endpoint       ||
             |          | (E) Metadata Response |+-------------------+|
             |          |    (Discover also     +---------------------+
             |          |     expected RAR types)
             |          |           :           +---------------------+
             |          |        RAR Types      |    Authorization    |
             |          | (F) Metadata Request  |       Server        |
             |          |---------------------->|+-------------------+|
             |          |                       ||     RAR Types     ||
             |          |<----------------------|| Metadata Endpoint ||
             |          | (G) Metadata Response |+-------------------+|
             |          |           :           |                     |
             |          | (H) Construct RAR     |                     |
             |          |     Using Metadata    |                     |
             |          |        :              |                     |
             |          | (I) Authorization     |                     |
             |          |     Request + RAR     |                     |
             |          |---------------------->|+-------------------+|
             |          |                       ||   Authorization   ||
             |          |<----------------------||     Endpoint      ||
             |          | (J) Authorization Code||                   ||
             |          |        :              |+-------------------+|
             |          |        :              |                     |
             |          | (K) Token Request     |+-------------------+|
             |          |---------------------->||                   ||
             |          |                       ||   Token Endpoint  ||
             |          |<----------------------||                   ||
             |          | (L) Access Token      |+-------------------+|
             |          |        :              +---------------------+
             |          |        :
             |          | (M) API Call with
             |          |     Access Token      +---------------------+
             |          |---------------------->|                     |
             |          |                       |   Resource Server   |
             |          |<----------------------|                     |
             |          | (N) 200 OK + Resource +---------------------+
             |          |
             +----------+

Figure: Client obtains 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 the resource metadata url (OAuth 2.0 Protected Resource Metadata [RFC9728]).

  • (D-E) The client discovers expected authorization details types from resource metadata endpoint's response.

  • (F-G) The client consumes authorization details type metadata from authorization server's authorization_details_types_metadata_endpoint.

  • (H-I) The client constructs a valid authorization details object and makes an OAuth + RAR [RFC9396] request.

  • (J) Authorization server returns authorization code.

  • (K-L) The client exchanges authorization code for access token.

  • (M) The client makes an API request with the (RAR) access token.

  • (N) Resource server validates access token and returns successful response.

3.2. Client obtains authorization details object from resource server's error response 

                                                +--------------------+
             +----------+ (B) API Request       |                    |
             |          |---------------------->|      Resource      |
(A) User +---|          |                       |       Server       |
   Starts|   |          |<----------------------|                    |
   Flow  +-->|  Client  | (C) 403 Forbidden     +--------------------+
             |          |     WWW-Authenticate: Bearer
             |          |     error="insufficient_authorization_details",
             |          |     resource_metadata="[resource metadata url]"
             |          |        +
             |          |     HTTP body provides authorization_details
             |          |        :
             |          |        :              +--------------------+
             |          |        :              |   Authorization    |
             |          | (D) Authorization     |      Server        |
             |          |     Request + RAR     |+------------------+|
             |          |---------------------->||                  ||
             |          |                       ||  Authorization   ||
             |          |<----------------------||    Endpoint      ||
             |          | (E) Authorization Code||                  ||
             |          |        :              |+------------------+|
             |          |        :              |                    |
             |          | (G) Token Request     |+------------------+|
             |          |---------------------->||                  ||
             |          |                       || Token Endpoint   ||
             |          |<----------------------||                  ||
             |          | (H) Access Token      |+------------------+|
             |          |        :              +--------------------+
             |          |        :
             |          |        :
             |          | (I) Retry API Call    +--------------------+
             |          |     with Token        |                    |
             |          |---------------------->|      Resource      |
             |          |                       |       Server       |
             |          |<----------------------|                    |
             |          | (J) 200 OK + Resource +--------------------+
             |          |
             +----------+

Figure: Client obtains authorization details object from resource server's error response

  • (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 includes the authorization details object requiring approval.

  • (D) The client uses the obtained authorization details object in a new OAuth + RAR [RFC9396] request.

  • (E) Authorization server returns authorization code.

  • (G-H) The client exchanges authorization code for access token.

  • (I) The client makes an API request with the (RAR) access token.

  • (J) Resource server validates access token and returns successful response.

4. OAuth 2.0 Protected Resource Metadata [RFC9728]

This document specifies a new OPTIONAL metadata attribute: authorization_details_types_supported, to be included in the response of OAuth Protected Resource Metadata [RFC9728].

"authorization_details_types_supported":

OPTIONAL. a JSON object that conforms to the syntax described in Section 4.1 for a required types expression.

The following is a non-normative example response with the added authorization_details_types_supported attribute:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "resource":
    "https://resource.example.com/payments",
    "authorization_servers":
        ["https://as1.example.com",
        "https://as2.example.net"],
    "bearer_methods_supported": ["header"],
    "scopes_supported": ["payment"],
    "resource_documentation":
        "https://resource.example.com/docs/payments.html",
    "authorization_details_types_supported": {
        "oneOf": ["payment_initiation", "payment_approval",
                  "beneficiary_designation"]
    }
}

Note: When resource servers accept access tokens from several authorization servers, interoperability is maintained and confusion is prevented, because clients can discover which authorization details types each authorization server supports.

4.1. Required types expression syntax

The following JSON syntax defines a required types expression to declaratively describe permitted combinations of required authorization_details types. This expression allows selection operators (oneOf, allOf, constraints) 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:

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

"constraints":

OPTIONAL. a JSON object defining cardinality and exclusion constraints over a set of authorization_details types. The object MUST contain the types attribute and MAY contain the attributes min, max, exact, and forbidden. Constraints attributes definition:

"types":

REQUIRED. a non-empty JSON array of strings identifying the authorization_details types to which the constraints apply.

"min":

OPTIONAL. a non-negative integer indicating the minimum number of authorization_details types from types that MUST be present. This attribute MUST NOT be used together with the exact attribute.

"max":

OPTIONAL. a non-negative integer indicating the maximum number of authorization_details types from types that MAY be present. This attribute MUST NOT be used together with the exact attribute.

"exact":

OPTIONAL. a non-negative integer indicating the exact number of authorization_details types from types that MUST be present. This attribute MUST NOT be used together with the min or max attributes.

"forbidden":

OPTIONAL. a non-empty JSON array, whose each element is an array of authorization_details types identifiers, representing a combination that MUST NOT be present together.

4.2. Required types expression examples

4.2.1. Example expression using "and" operator

Specifies that the selection MUST include a and b, and one of c or d.

{
  "required_types": {
    "and": [
      { "allOf": ["a", "b"] },
      { "oneOf": ["c", "d"] }
    ]
  }
}

Specifies that the selection MUST include one of a or b, and exactly two of [c,d,e], but the combination of d and e together is forbidden.

{
  "required_types": {
    "and": [
      { "oneOf": ["a", "b"] },
      {
        "constraints": {
          "types": ["c", "d", "e"],
          "exact": 2,
          "forbidden": [["d", "e"]]
        }
      }
    ]
  }
}

4.2.2. Example expression using "or" operator

Specifies that the selection MUST include either c and d, or one of a or b.

{
  "required_types": {
    "or": [
      { "allOf": ["c", "d"] },
      { "oneOf": ["a", "b"] }
    ]
  }
}

4.2.3. Example expression using "constraints" operator

Specifies that at least two of {a,b,c} MUST be present, but the combination of a and c together is forbidden.

{
  "required_types": {
    "constraints": {
      "types": ["a","b","c"],
      "min": 2,
      "forbidden": [ ["a","c"] ]
    }
  }
}

Specifies that exactly two of {a,b,c} MUST be present.

{
  "required_types": {
    "constraints": {
      "types": ["a","b","c"],
      "exact": 2
    }
  }
}

5. Authorization Details Types Metadata Endpoint

The following authorization server metadata [RFC8414] parameter is introduced to signal the server's support for Authorization Details Types Metadata:

"authorization_details_types_metadata_endpoint":

OPTIONAL. The URL of the Authorization Details Types Metadata endpoint.

5.1. Authorization Details Types Metadata Endpoint Response

The Authorization Details Types Metadata endpoint's response is a JSON document with the key authorization_details_types_metadata whose attributes are authorization details type identifiers.

Each identifier is an object describing a single authorization details type.

{
  "authorization_details_types_metadata": {
    "type": {
      "version": "...",
      "description": "...",
      "documentation_uri": "...",
      "schema": { },
      "schema_uri": "...",
      "examples": [ ]
    }
  }
}

Attributes definition:

"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 human-readable description of the authorization details type. Clients MUST NOT rely on this value for authorization or validation decisions.

"documentation_uri":

OPTIONAL. URI referencing external human-readable documentation describing the authorization details type.

"schema":

The schema attribute is a JSON Schema document [JSON.Schema] describing a single authorization detail object. The schema MUST validate a single authorization detail object and MUST constrain the type attribute to the authorization detail type identifier. This attribute is REQUIRED unless schema_uri is specified. If this attribute is present, schema_uri MUST NOT be present.

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

6. Resource Server Error Signaling of Inadequate authorization_details

This document defines a new normative OAuth error code, insufficient_authorization_details, which resource servers SHALL return using the WWW-Authenticate header, to signal access is denied due to missing or insufficient authorization details.

Example HTTP response:

HTTP/1.1 403 Forbidden
WWW-Authenticate: Bearer error="insufficient_authorization_details",
    resource_metadata="https://resource.example.com/
    .well-known/oauth-protected-resource/payments"

6.1. OPTIONAL authorization_details in response body

Resource server MAY provide alongside the insufficient_authorization_details error, an informative HTTP response body of content type application/json, containing required authorization details objects to satisfy the currently failing request.

Note:

  • The audience of authorization details objects provided by a resource server in an error response are its trusted authorization servers, as advertised by the Resource Server’s metadata endpoint.

  • Resource servers SHALL provide authorization_details objects only if all trusted authorization servers accept the authorization details type 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.

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:

HTTP/1.1 403 Forbidden
WWW-Authenticate: Bearer error="insufficient_authorization_details",
    resource_metadata="https://resource.example.com/
    .well-known/oauth-protected-resource/payments"
Content-Type: application/json
Cache-Control: no-store

{
  "authorization_details": [{
    "type": "payment_initiation",
    "instructedAmount": {
      "currency": "EUR",
      "amount": "100.00"
    },
    "creditorAccount": {
      "iban": "DE02120300000000202051"
    }
  }]
}

7. Processing Rules

7.1. Client Processing Rules

  • If encountering error insufficient_authorization_details, check if body.authorization_details exists and if provided MAY include in subsequent OAuth request.

  • Otherwise consult metadata:

    • Fetch resource metadata to discover accepted authorization servers and supported authorization_details types.

    • Fetch authorization server metadata to discover authorization_details_types_supported.

    • Fetch authorization server's authorization_details_types_metadata_endpoint to obtain metadata and schema

    • Locate schema or retrieve schema_uri.

  • Construct authorization details conforming to the schema and include in subsequent OAuth request.

7.2. Resource Server Processing Rules

  • Advertise in resource metadata authorization_details_types_supported, where relevant.

  • Verify access tokens against required authorization details.

  • If insufficient, return HTTP 403 with WWW-Authenticate: Bearer error="insufficient_authorization_details".

  • OPTIONALLY provide also an HTTP body with an informative actionable authorization_details object.

8. Security Considerations

8.1. Cacheability and Intermediaries

HTTP 403 responses with response bodies may be cached or replayed in unexpected contexts. Recommended mitigation is resource servers SHALL use Cache-Control: no-store response header.

9. IANA Considerations

9.1. OAuth 2.0 Bearer Token Error Registry

Table 1
Error Code Description
insufficient_authorization_details The request is missing required authorization details or the provided authorization details are insufficient.

9.2. OAuth Metadata Attribute Registration

The metadata attribute authorization_details_types_metadata_endpoint is defined for OAuth 2.0 authorization server metadata as a URL. The metadata attribute authorization_details_types_supported is defined for OAuth 2.0 protected resource metadata.

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 Postman, B., and G. Dennis, "JSON Schema: A Media Type for Describing JSON Documents", , <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, , <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, , <https://www.rfc-editor.org/rfc/rfc3986>.
[RFC6749]
Hardt, D., Ed., "The OAuth 2.0 Authorization Framework", RFC 6749, DOI 10.17487/RFC6749, , <https://www.rfc-editor.org/rfc/rfc6749>.
[RFC8174]
Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, , <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, , <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, , <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, , <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

{
    "authorization_details_types_metadata": {
        "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",
                "title": "Payment Initiation Authorization Detail",
                "type": "object",
                "required": [
                    "type",
                    "instructed_amount",
                    "creditor_account"
                ],
                "properties": {
                    "type": {
                        "const": "payment_initiation",
                        "description": "Authorization detail 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})?$"
                            }
                        },
                        "additionalProperties": false
                    },
                    "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}$"
                            }
                        },
                        "additionalProperties": false
                    },
                    "remittance_information": {
                        "type": "string",
                        "description": "Unstructured remittance information for the payment.",
                        "maxLength": 140
                    }
                },
                "additionalProperties": false
            }
        }
    }
}

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

{
    "authorization_details_types_metadata": {
        "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"
                                            },
                                            "value": {
                                                "type": "string"
                                            }
                                        },
                                        "required": [
                                            "system",
                                            "type",
                                            "value"
                                        ]
                                    }
                                },
                                "required": [
                                    "identifier"
                                ]
                            }
                        },
                        "required": [
                            "organization"
                        ]
                    }
                },
                "required": [
                    "type",
                    "practitioner_role"
                ]
            }
        },
        "helseid_trust_framework": {
            "$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": {
                                "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"
                                },
                                "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"
                            ]
                        },
                        "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": {
                                    "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. Protected Resource Metadata Examples

A.2.1. Example Protected Resource Metadata response of payments resource 

HTTP/1.1 200 OK
Content-Type: application/json

{
    "resource": "https://resource.example.com/payments",
    "authorization_servers":
        ["https://as1.example.com",
        "https://as2.example.net"],
    "bearer_methods_supported": ["header"],
    "scopes_supported": ["payment"],
    "resource_documentation":
        "https://resource.example.com/docs/payments.html",
    "authorization_details_types_supported": {
        "oneOf": ["payment_initiation", "payment_approval",
                  "beneficiary_designation"]
    }
}

A.2.2. Example Protected Resource Metadata response from the Norwegian Health Sector (HelseID) 

HTTP/1.1 200 OK
Content-Type: application/json

{
    "resource": "https://health-api.nhn.no/health-information",
    "authorization_servers": ["https://helseid-sts.nhn.no"],
    "bearer_methods_supported": ["header"],
    "scopes_supported":
        ["nhn:health-api/read", "nhn:health-api/write"],
    "resource_documentation": "https://utviklerportal.nhn.no",
    "authorization_details_types_supported": {
        "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

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"
    ],
    "instructedAmount": {
        "currency": "EUR",
        "amount": "123.50"
    },
    "creditorName": "Merchant A",
    "creditorAccount": {
        "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:

HTTP/1.1 403 Forbidden
WWW-Authenticate: Bearer error="insufficient_authorization_details",
    resource_metadata="https://resource.example.com
    /.well-known/oauth-protected-resource/payments"
Content-Type: application/json
Cache-Control: no-store

{
    "authorization_details": [{
      "type": "payment_initiation",
      "locations": [
          "https://example.com/payments"
      ],
      "instructedAmount": {
          "currency": "EUR",
          "amount": "123.50"
      },
      "creditorName": "Merchant A",
      "creditorAccount": {
          "bic": "ABCIDEFFXXX",
          "iban": "DE02100100109307118603"
      },
      "interactionId": "f81d4fae-7dec-11d0-a765-00a0c91e6bf6",
      "riskProfile": "B-71"
}]
}

Note: the resource server has added the ephemeral attributes interactionId and riskProfile.

A.3.3. Client initiates OAuth flow using the provided authorization_details object

After user approves the request, client obtains single-use access token representing the approved payment

A.3.4. Client re-attempts API request 

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"
    ],
    "instructedAmount": {
        "currency": "EUR",
        "amount": "123.50"
    },
    "creditorName": "Merchant A",
    "creditorAccount": {
        "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

-02

-01

-00

Acknowledgments

The authors would like to thank the following individuals who contributed ideas, feedback, and wording that shaped and formed the final specification: Rune Grimstad.

Author's Address

Yaron Zehavi
Raiffeisen Bank International