30 Mar 2023
Migration guide - OAuth2 v1 to v2
Updated October 5th, 2023: Important Update: Authentication v1 Deprecation Extended to April 30th, 2024 – Act Now! Please see here for the announcement.
Authentication (OAuth) v2 is now available, offering alignment with OpenID specs and PCKE workflow (for desktop & SPA apps), among performance and modern technology stack. This article show show to migrate your code. The complete documentation is available here. For additional queries, please reach out on aps.help@autodesk.com.
Migrate from OAuth 2 V1 to V2 endpoints for 2L tokens
To migrate from OAuth 2 V1 to V2, requires a simple change in the way client credentials are being passed in the request. V1 API accepts client id and client secrets in the request body. Whereas V2 accepts client id and client secret in the Authorization header with Basic auth type. Note :- Please write "B" in "Basic" in uppercase.
1. The base URL changes from –
APS_HOST/authentication/v1/authenticate
To
APS_HOST/authentication/v2/token
2. Request Parameters in V1 is using client credentials in the body whereas
V2 requires clients credentials in headers with Authorization: Basic
Authorization must be in the form Basic ${Base64(<client_id>:<client_secret>)}
3. The Header (Request Parameters) changes from –
Content-Type: application/x-www-form-urlencoded
To
Content-Type: application/x-www-form-urlencoded
Authorization: Basic RG4ydUlwOGp1S0hzRmV1WHV0bmtmZ0FQWHFkdWx5WHA6b01YZWEyMEZVY3Q0REJqYw=
4. The Body (Request Parameters) changes from –
client_id=obQDn8P0GanGFQha4ngKKVWcxwyvFAGE
client_secret=xyz
grant_type=client_credentials
scope=data:read
To
grant_type=client_credentials
scope=data:read
5. No Change in the API response
6. The change in curl command –
curl -v 'APS_HOST/authentication/v1/authenticate'
-X 'POST'
-H 'Content-Type: application/x-www-form-urlencoded'
-d ' client_id=obQDn8P0GanGFQha4ngKKVWcxwyvFAGE&client_secret=eUruM8HRyc7BAQ1e& grant_type=client_credentials& scope=data:read '
To
curl --location -g --request POST 'APS_HOST/authentication/v2/token' \
--header 'Authorization: Basic RG4ydUlwOGp1S0hzRmV1WHV0bmtmZ0FQWHFkdWx5WHA6b01YZWEyMEZVY3Q0REJqYw==' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'scope=data:read'
7. The APS document link also changes-
https://aps.autodesk.com/en/docs/oauth/v1/tutorials/get-2-legged-token/
To
https://aps.autodesk.com/en/docs/oauth/v2/tutorials/get-2-legged-token/
Migrate from OAuth 2 V1 to V2 endpoints for 3L tokens
Only change in the /authorize endpoint is the version number from v1 to V2.
1. The base URL changes its version number from –
APS_HOST/authentication/v1/authorize
To
APS_HOST/authentication/v2/authorize
2. The change in curl command is –
curl --location -g --request ‘APS_HOST/authentication/v1/authorize?
response_type=code
&client_id=obQDn8P0GanGFQha4ngKKVWcxwyvFAGE
&redirect_uri=http%3A%2F%2Fsampleapp.com%2Foauth%2Fcallback%3Ffoo%3Dbar
&scope=data:read
To
curl --location -g --request GET 'APS_HOST/authentication/v2/authorize?
response_type=code
&client_id=obQDn8P0GanGFQha4ngKKVWcxwyvFAGE
&redirect_uri=http%3A%2F%2Fsampleapp.com%2Foauth%2Fcallback%3Ffoo%3Dbar
&scope=data:read
3. The aps doc changes from
https://aps.autodesk.com/en/docs/oauth/v1/tutorials/get-3-legged-token/
To
https://aps.autodesk.com/en/docs/oauth/v2/tutorials/get-3-legged-token/
Exchange the Authorization code for Access Token
1. The base URL changes from –
APS_HOST/authentication/v1/gettoken
To
APS_HOST/authentication/v2/token
2. V1 is using client credentials in the body
V2 requires clients credentials in headers with Authorization: Basic
Authorization must be in the form Basic ${Base64(<client_id>:<client_secret>)}
V2 accepts application/json in the header
3. The Header (Request Parameters) changes from –
Content-Type: application/x-www-form-urlencoded
To
Content-Type: application/x-www-form-urlencoded
Authorization: Basic RG4ydUlwOGp1S0hzRmV1WHV0bmtmZ0FQWHFkdWx5WHA6b01YZWEyMEZVY3Q0REJqYw==
Accept: application/json
4. The Body (Request Parameters) changes from –
grant_type=authorization_code
client_id=obQDn8P0GanGFQha4ngKKVWcxwyvFAGE
client_secret=eUruM8HRyc7BAQ1e
redirect_uri=http%3A%2F%2Fsampleapp.com%2Foauth%2Fcallback%3Ffoo%3Dbar
code=wroM1vFA4E-Aj241-quh_LVjm7UldawnNgYEHQ8I
To
grant_type=authorization_code
redirect_uri=http%3A%2F%2Fsampleapp.com%2Foauth%2Fcallback%3Ffoo%3Dbar
code=wroM1vFA4E-Aj241-quh_LVjm7UldawnNgYEHQ8I
5. No Change in the API response
6. The change in curl command –
curl -v 'APS_HOST/authentication/v1/gettoken' \ -X 'POST' \ -H 'Content-Type: application/x-www-form-urlencoded' \ -d 'client_id=obQDn8P0GanGFQha4ngKKVWcxwyvFAGE' \ -d 'client_secret=eUruM8HRyc7BAQ1e' \ -d 'grant_type=authorization_code' \ -d 'code=wroM1vFA4E-Aj241-quh_LVjm7UldawnNgYEHQ8I' \ -d 'redirect_uri=http://sampleapp.com/oauth/callback'
To
curl -v 'APS_HOST/authentication/v2/token' -X 'POST' -H 'Content-Type: application/x-www-form-urlencoded'' -H 'accept: application/json' \' -d 'grant_type=authorization_code' -d 'code=wroM1vFA4E-Aj241-quh_LVjm7UldawnNgYEHQ8I' -d 'redirect_uri=http://sampleapp.com/oauth/callback'
7. The link of the APS document also changes-
https://aps.autodesk.com/en/docs/oauth/v1/reference/http/gettoken-POST/
To
https://aps.autodesk.com/en/docs/oauth/v2/reference/http/gettoken-POST/#section-1-authorization-code-grant-type
Refresh Token
8. The base URL changes from –
https://developer.api.autodesk.com/authentication/v1/refreshtoken
To
https://developer.api.autodesk.com/authentication/v2/token
9. V1 is using client credentials in the body
V2 requires clients credentials in headers with Authorization: Basic
Authorization must be in the form Basic ${Base64(<client_id>:<client_secret>)}
V2 accepts application/json in the header
10. The Header (Request Parameters) changes from –
Content-Type: application/x-www-form-urlencoded
To
Content-Type: application/x-www-form-urlencoded
Authorization: Basic RG4ydUlwOGp1S0hzRmV1WHV0bmtmZ0FQWHFkd
Wx5WHA6b01YZWEyMEZVY3Q0REJqYw==
Accept: application/json
11. The Body (Request Parameters) changes from –
grant_type=refresh_token
client_id=obQDn8P0GanGFQha4ngKKVWcxwyvFAGE
client_secret=eUruM8HRyc7BAQ1e
refresh_token=Jnrqqp7b8GrfqIE53WocjEyt59RClDYhqbYeOCWeqM
scope=data:read
To
grant_type=refresh_token
refresh_token=Jnrqqp7b8GrfqIE53WocjEyt59RClDYhqbYeOCWeqM
scope=data:read
12. No Change in the api response
13. The change in curl command –
curl -v 'https://developer.api.autodesk.com/authentication/v1/refreshtoken' -X 'POST' -H 'Content-Type: application/x-www-form-urlencoded' -d ' client_id=obQDn8P0GanGFQha4ngKKVWcxwyvFAGE& client_secret=eUruM8HRyc7BAQ1e& grant_type=refresh_token& refresh_token=i0kBWTHzI0JVKWTOoFn6cvPk32SZcs5CUtwic3ndu
To
curl -v 'https://developer.api.autodesk.com/authentication/v2/token' -X 'POST' -H 'Content-Type: application/x-www-form-urlencoded' -H 'Accept: application/json' -H 'Authorization: Basic YWthc2h0ZXN0OmFrYXNodGVzdA==' \ -d 'grant_type=refresh_token' -d 'refresh_token=Jnrqqp7b8GrfqIE53WocjEyt59RClDYhqbYeOCWeqM' -d 'scope=data:read'
14. The aps doc changes from-
https://aps.autodesk.com/en/docs/oauth/v1/reference/http/refreshtoken-POST/
To
https://aps.autodesk.com/en/docs/oauth/v2/reference/http/gettoken-POST/
Introducing Invalidate Refresh Token / Access token with v2
1. The base URL –
https://developer.api.autodesk.com/authentication/v2/revoke
2. Headers –
Content-Type: application/x-www-form-urlencoded
Authorization: Basic RG4ydUlwOGp1S0hzRmV1WHV0bmtmZ0FQWHFkd
Wx5WHA6b01YZWEyMEZVY3Q0REJqYw==
3. Body-
token_type_hint=refresh_token
refresh_token=Jnrqqp7b8GrfqIE53WocjEyt59RClDYhqbYeOCWeq
4. Curl Command-
curl -v 'https://developer.api.autodesk.com/authentication/v2/revoke' -X 'POST' -H 'Content-Type: application/x-www-form-urlencoded' -d '{ 'token=9uACOhcF7d94rYJDKmulcyssEeyZ4HVNTwqng6Qekt' \ 'token_type_hint=refresh_token' \ 'client_id=0oawv18w63i03CgmZ0h7' }
5. Document Link-
6. https://aps.autodesk.com/en/docs/oauth/v2/reference/http/revoke-POST/