I reviewed this document as part of the security directorate's ongoing effort to review all IETF documents being processed by the IESG.   These comments were written with the intent of improving security requirements and considerations in IETF drafts.   Comments not addressed in last call may be included in AD reviews during the IESG review.   Document editors and WG chairs should treat these comments just like any other last call comments.   This document describes an API for use with OAuth 2.0. The API enables the recipient of a token to query an authorization server to determine the set of metadata presented to the server (by the OAuth client) when the token was issued. This API is intended to overcome the lack of a standard way to convey token metadata in the OAuth 2.0 context.   I didn’t find any significant security problems with the document, but there are a number of places where the exposition needs improvement.   Specific comments   Section 2   The text says:      The introspection endpoint MUST be protected by a transport-layer security mechanism as described in Section 4.   It might be clearer to say here that the token endpoint MUST communicate security with the introspection endpoint, and that TLS 1.2 is the mandatory-to-implement mechanism for such security. Also, the text should be clearer about the relationship between an authorization server and an introspection endpoint. In some places the two terms seem to be used interchangeably.   Section 2.1   The texts says:   The endpoint MAY allow other parameters to provide further context to the query.     How about:   The endpoint MAY accept other parameters to provide further context to the query.     How does a protected resource know which other parameters an introspection endpoint requires/accepts?     This section mandates (MUST) protection against “unauthorized token scanning” but mandates no standard way to do so. [Also, when would a scanning “attack” be authorized ;-)]     The text says:   For example, the following example shows a protected resource calling the token introspection endpoint to query about an OAuth 2.0 bearer.   How about:   For example, the following example shows a protected resource calling the token introspection endpoint to query about an OAuth 2.0 bearer token .     Section 2.2   He text says:      The authorization server MAY respond differently to different    protected resources making the same request.   For instance, an    authorization server MAY limit which scopes from a given token are    returned for each protected resource in order to prevent protected    resources from learning more about the larger network than is    necessary for their function.   How about:      An authorization server MAY respond differently to different    protected resources making the same request.   For instance, an    authorization server MAY limit which scopes from a given token are    returned to each protected resource in order to prevent a protected    resources from learning more about the larger network than is    necessary for its operation .     Section 3.1   Experience suggests a longer review period is appropriate, e.g., to accommodate holidays, vacations, etc.   The text says:   IANA must only accept registry updates from the Designated Expert(s) and should direct all requests for registration to the review mailing list.   How about:   IANA MUST accept registry updates only from the Designated Expert(s) and SHOULD direct all requests for registration to the review mailing list.   Section 3.1.1   If a proposed Name matches one already registered as per 7519, ought it not have an “equivalent” (vs. “comparable”) definition if it is to be accepted?     Section 4   The text lists four checks to be performed by an authorization server, yet the introduction to this list says “For instance:” A more normative introduction would seem appropriate here. I realize that the text says that not all of these checks may be applicable in all OAuth 2.0 contexts, but since each check begins with “If the token …” isn’t that a sufficient caveat?   The text says:   If an authorization server fails to perform any applicable check, the resource server could make an errant security decision based on that response.     How about:   If an authorization server fails to perform any applicable check, the resource server could make an erroneous security decision based on that response.       The text says:   per RFC 6125 [RFC6125].   How about:   as specified in [RFC6125].     The discussion of introspection endpoint response caching seems to omit a simple, useful heuristic. Since the expiration time for a token is an optional parameter in the response, why not say that IF this parameter is present, the response MUST NOT be cached beyond that time?     Section 5   This section says: “One way to limit disclosure is to require authorization to call the introspection endpoint and to limit calls to only registered and trusted protected resource servers.” But   Section 4 says: “… the authorization server MUST require authentication of protected resources that need to access the introspection endpoint and SHOULD require protected resources to be specifically authorized to call the introspection endpoint.”   It seems that the requirement imposed in Section 4 already mandate what is merely suggested in Section 5.