Cloud SDK: "Generate an access token" section is missing some info

[BryanKadzban]

https://docs.particle.io/reference/device-cloud/api/#generate-an-access-token

Unfortunately I don't see where the sources for this part of the docs are stored; they're not in this repository, as searching it for "joe@example.com" (in the example set of requests) or "oauth grant type" (in the description of the grant_type form field) finds nothing.

One issue is that the grant_type field is very under-documented. It's true that a pure username and password login to a developer account uses the "password" grant_type. But if your developer account has MFA turned on, you get an mfa_required error code with an mfa_token field, but nowhere in the docs does it say what to do with that. You have to set grant_type to urn:custom:mfa-otp, set otp to the six-digit code from the external authenticator, and set mfa_token to the token string that the error response sent. (Per https://community.particle.io/t/rest-cloud-api-multifactor-response/51062)

It would be much better if the grant_type field had full documentation on the different accepted types. password is given already; it requires the username and password fields. client_credentials is used for products (it would be good to link to the explanation in the device-cloud authentication tutorial, and outline which form fields are required). urn:custom:mfa-token requires mfa_token and otp (and I'm also re-sending the username and password in my client ... but I don't know if that's required).

A second issue is that the "refresh_token" field in a successful response is also under-documented. It says "used to generate a new access token when it has expired", but this is not entirely true; the refresh tokens also only work for a product, not for "normal" developer account logins. That's documented elsewhere (in the authentication tutorial), but should be here too since it's part of the API.

I would generate both of these changes and make a pull request, but I can't find them in the repository. I did find the note at the top of https://github.com/particle-iot/docs/blob/master/src/content/reference/device-cloud/api.md though, saying to open a GitHub issue instead of changing the doc. So here I am.

[ventz]

@BryanKadzban - Thank you for posting this. I was going crazy trying to figure out what was wrong given the mfa_token error, but nothing else in the Particle Documentation.

For anyone else, just to summarize -- you need 2 requests:

First:

curl https://api.particle.io/oauth/token \
-u particle:particle \
-d grant_type=password \
-d "username=email@domain.tld"

This will produce an error like -- note the mfa_token.

Example:

{"mfa_token":"6e16f915-29f5-9b2b-b752-451a73xec610","error":"mfa_required","error_description":"Multi-factor authentication required"}

And then, using the mfa_token above + your 6 digit TOTP in otp

curl https://api.particle.io/oauth/token \
-u particle:particle \
-d grant_type=urn:custom:mfa-otp \
-d "username=email@domain.tld" \
-d "mfa_token=6e16f915-29f5-9b2b-b752-451a73xec610" \
-d "otp=######"

Which will produce the:

{"token_type":"bearer","access_token":"ABC...","expires_in":7776000,"refresh_token":"XYZ..."}