OAuth - How to Check if access_token is Expired

[Jeff_New_Ocean]

I'm not clear from the documentation what the correct process is to determine the status of an access_token. 

Is it correct that I need to make an attempt to get a user's data with the existing access_token first, and then if I get the 401-UNAUTHORIZED because the access_token is expired, that's when I would request a new access_token using the refresh_token?

Or is there an endpoint that I can call with the sole purpose is to check the access_token status?

[Jeff_New_Ocean]

UPDATE: After reading through the Web API docs again, I see that there is oauth2/introspect endpoint that will get the status of a access_token. So that leaves two options for managing the access_token:

1.  Respond to a 401-UNAUTHORIZED response from attempted user data request.

     a. If the access_token is still valid, it would be one request

         1) Make request to get user data with existing access_token; data is returned

     b. If the access_token is NOT valid, it would be three requests

         1) Make request to get user data with existing access_token; 401-UNAUTHORIZED is returned.

         2) Make request to get new access_token using refresh_token

         3) Make request to get user data using new access_token; data is returned

2.  Use the /introspect endpoint to check the access_token before every user data call. In that case

     a. If the access_token is still valid, it would be two requests

         1) Call /introspect to check status of access_token; returns that token is valid.

         2) Make request to get user data with existing access_token; data is returned

     b. If the access_token is NOT valid, it would be three requests

         1) Call /introspect to check status of access_token; returns that token is NOT valid.

         2) Make request to get new access_token using refresh_token

         3) Make request to get user data using new access_token; data is returned

After typing this out, option 1 (using the 401 as a trigger to get a new access_token) seems to be the better option, because either way the NOT valid token path is 3 requests, but Option 1's valid path is only one request.

Also, I believe, after reading thru the Web API document a few more times, that Option 1 is what is being alluded to in the "Refreshing Tokens" section of the "Authentication" section, although it doesn't state what request is being made that is returning the 401 response.

Thanks in advance for any assistance, comments or clarification.

Thanks!

[JohnFitbit · Accepted solution]

Hi @Jeff_New_Ocean,

We're releasing a new version of the authorization code grant flow process as the current documentation can be confusing at times.

I hope these steps will provide clarification for you in the meantime:

1. Your application presents to the user the Fitbit Authorization page by calling the "authorize" endpoint.  See Authorization Page.
2. The user consents to share their Fitbit data with your application by enabling the scopes. Upon the user’s initial consent, Fitbit redirects the user back to your application using the redirect or callback URL with an authorization code as a URL parameter.
3. Your application exchanges the authorization code it receives from step 2 for an access token and refresh token pair.  See Access Token Request below.  Your application should store the access token and refresh token.
4. The application uses the access token to execute API calls.  The refresh token is used to renew the access token when it expires without having to re-prompt the user.
5. Access tokens created through the authorization code grant flow have a lifespan of 8 hours.  When the user’s access token expires, your application will use the refresh token to obtain a new access token and refresh token pair.  See Refreshing Tokens.  Refresh tokens can only be used once.  Therefore, the old refresh token should be discarded and your application should store the new access token and refresh token pair.

Also, I believe, after reading thru the Web API document a few more times, that Option 1 is what is being alluded to in the "Refreshing Tokens" section of the "Authentication" section, although it doesn't state what request is being made that is returning the 401 response.

---

When using an expired access token in the authorization header of any HTTP request, you will see a 401 Unauthorized error returned. When you receive the 401 Unauthorized error, you'll need to use the refresh token that you received after consent to obtain a new access token and refresh token pair using the Token Refresh endpoint.

I hope this helps clarify. Please let me know if you have any additional questions.