Authorization grants in OAuth 2.0 security scheme


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:

  • code / authorization_code
  • token / (not a grant type)
  • owner / password
  • credentials / client_credentials

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.


Hi Walling, just a bit more information, here is the 4 grant types and their translation to RAML:

RAML: code -----> OAuth2: authorization code
RAML: token ------> OAuth2: implicit
RAML: owner ------> OAuth2: resource owner password credentials
RAML: credentials -------> OAuth2: client credentials

We may want to consider renaming them in RAML to the OAUth2 cannonical names in future versions of raml to avoid confusion.

About extensions, I’ll let somebody with more knowledge reply.