Documentation improvement

[mbierman]

First and foremost, thanks for all you do. 👍🏻

Instructions for nest accounts talks about grabbing the access_token. In the response from https://home.nest.com/session there are actually two access_tokens. I suggest describing which one to grab. One works, one doesn't. :)

I was having trouble with my nests so I thought i would go grab a new token and of course, grabbed the wrong one initially. After some debugging I found the problem and all is good now. Example response:

{
   "2fa_state":"enrolled",
   "access_token":"Use This ONE",
   "primary_phone":"+&&&",
   "email":"mmm@Nnn.com",
   "expires_in":"Thu, 12-May-2022 19:22:10 GMT",
   "urls":{
      "rubyapi_url":"https://home.nest.com/",
      "czfe_url":"https://czfe51-front01-iad01.transport.home.nest.com",
      "log_upload_url":"https://logsink.home.nest.com/upload/user",
      "transport_url":"https://czfe51-front01-iad01.transport.home.nest.com",
      "weather_url":"https://apps-weather.nest.com/weather/v1?query=",
      "support_url":"https://nest.secure.force.com/support/webapp?",
      "direct_transport_url":"https://transport03-rts15-iad01.transport.home.nest.com:443"
   },
   "2fa_enabled":true,
   "userid":"114611",
   "2fa_state_changed":"2018-05-24 17:57:46.0",
   "is_superuser":false,
   "language":"en_US",
   "weave":{
      "service_config":"",
      "pairing_token":"",
      "access_token":"Do not use this one"
   },
   "limits":{
      "thermostats_per_structure":20,
      "structures":3,
      "smoke_detectors_per_structure":18,
      "smoke_detectors":54,
      "thermostats":60
   },
   "user":"user.114611",
   "is_staff":false
}

[adriancable]

@mbierman - thanks for the suggestion - I'm not sure it really adds to the clarity. In the original docs, it shows an example response:

{"2fa_state":"not_enrolled","access_token":"XXX","email":"...","expires_in":"...", ...}

Then it says use the XXX. This is very similar to your example, except you've used "Use This One" instead of the "XXX". I think in both examples it's clear that the token you use is the one immediately after the 2fa_state: non_enrolled part.

Open to being convinced otherwise! :-)

[mbierman]

I would respectfully disagree. The example provided is:

which only shows the first access_token. I'm suggesting you show a bit more and highlight (in whatever way you like) that the first one is the right one.

[adriancable]

@mbierman - I always appreciate respectful disagreement! I will take another look.

[adriancable]

@mbierman - I have improved the documentation for this in 4.6.7. Feel free to re-open if you feel it's still unclear.