TL;DR: How do we document OAuth 2.0 extension grant types in the securitySchemes settings in RAML?
Right now the following values are allowed in the
authorizationGrants settings (from the 0.8 spec): code, token, owner or credentials. The OAuth 2.0 spec allows extension grants, ie. custom values for the grant_type parameter, and we are using that in our API. How should we document it?
It might not be feasible to make
authorizationGrants in the RAML spec in alignment with the grant types of the OAuth 2.0 spec;
token is for example not a grant type per se, but a flow based on the authorization endpoint. It could however be nice to allow custom URIs in
authorizationGrants if people want to document their extension grant types.
Here is a list of authorization grants in RAML vs. the grant type in OAuth 2.0:
token/ (not a grant type)
I’m not mentioning
refresh_token as it is a special grant type and it’s another discussion. I want to focus on how to document extension grant types.
Extension grant types allows your API to authorize resource owners (ie. users) in other ways than specified. Read more in OAuth 2.0 section 4.5.