Clarify properties in access token grant response description and example

[barnabywalters]

https://indieauth.spec.indieweb.org/#access-token-response states that the following properties must/should/may be present in access token grant responses:

• access_token (required)
• me (required)
• profile (optional)
• expires_in (recommended)
• refresh_token (optional)

The example additionally includes token_type and scope. Some applications (e.g. Quill) require scope, and the fact that scopeless token requests are invalid implies that scope might be required.

Pending clarification, I’d suggest the following changes:

• Update the list of possible properties in the access token response, including all required properties and noting all commonly used optional/recommended properties, linking to relevant specifications which reference them as with refresh_token
• Clarify in the text whether it’s permitted to include additional properties in the response, and under which circumstances
• Provide two examples, one of a minimal response containing only the absolutely required properties, and another with a variety of optional properties

Relevant conversation: https://chat.indieweb.org/dev/2022-09-19#t1663626755838500

[vikanezrimaya]

The fact that Quill requires a scope property on responses is probably a remnant of an older version of the spec. It makes sense for an app to know which permissions were granted to it, even though it introduces some potential for abuse (for example, an app forcing the user to re-login if it sees that a permission it wants to use maliciously is not granted to it, or maliciously restrict functionality unrelated to the permission as revenge). I suppose adding that to the spec would be nice, though I am not sure if it is meant to be optional or required. Are there implementations in the wild that do not have scope on access token grant responses besides Kittybox, in which the issue was uncovered?

[aaronpk]

The token response should match OAuth 2.

• token_type=Bearer is required
• scope is required if it differs from what the client requested, otherwise it's optional

[dshanske]

Any reason we shouldn't do a PR to address though?