14 Aug 2017
About Refresh Token
Update (September 2023)
There is a new version of this article that applies to Authentication v2.
Original post (now deprecated)
As this is actually a recurrent question, let's summarize how to use the refresh token on with Authentication. This article will focus on 3-legged workflow, as on a 2-legged workflow the app can simply request a new access token.
Starting from a GET authorize, when a user enters his/her Autodesk credential and redirect, your application receives a callback with the code, which can be used to POST getToken the access token & refresh token pair. This is the basis for authentication & authorization, so far so good. Now a few scenarios:
Persistent access to the app
That's probably the original usage for refresh token: a user accesses your app, sign in, your app gets the access token and stores the refresh token (on a database, for instance). Later, when the user returns, the apps identify the user via Cookie (or some other way) and uses the refresh token to get a new access token (automatically generating a new refresh token that needs to be stored/persisted).
Getting shareable access token
For this example, let's assume the original GET authorize request was performed with data:read & data:write scope, therefore the POST getToken was performed with this same scope. As the app will be using Viewer, we need an access token with restricted scope to send to the client (in case your app is not using proxy, which still the best solution).
Right after the first POST getToken, the application can perform a POST refreshToken with the same or a more restricted scope. In this example, the first call uses data:read data:write and the second uses only viewables:read. The second call uses the refresh token, which invalidates it, but will return a new refresh token.
Summary (so far)
For both scenarios, the refresh token will only expire after 14 days and can only be used once. That's important. As soon as your app uses the refresh token to get a new (or restricted scope) access token, the call returns new refresh token and the original refresh token is invalidated.
Multiple access
Now another scenario: a user sign in, your application gets an access & refresh token pair, then the same user sign in again, you get a second access & refresh token. At this point, the first refresh token is invalidated, but both access tokens are still valid (until their respective expires in time). This means Autodesk will keep only 1 refresh token for each user on a specific app.