New V2 API OAuth Resources and Refresh Tokens

June 13, 2023
5 minute read

We’re excited to announce the introduction of refresh tokens along with full OAuth flow support to version 2.0 of the Acquia DAM API. We’ve also redesigned the OAuth allow access page and token formats.

Version 2.0 OAuth endpoints

For many years we’ve only supported the entire OAuth flow via version 1.0 of the API, but now it’s available in v2.0. New endpoints have been added to support additional functionality and promote a more secure implementation over v1.0. It’s recommended that you switch from v1.0 to v2.0 to take advantage of this new functionality.

Access token generation

We decided to support two grant types with the implementation of the token exchange endpoint – authorization_code and refresh_token. More details about those are below.

The password grant type is not supported in v2.0 due to the security implications and its deprecation in the OAuth 2.0 specification. The password grant type is currently still functional in v1.0.

Access tokens can be generated via the following endpoint:

POST /v2/oauth/access-token

Authorization code grant

The authorization code grant type functions similar to the v1.0 exchange endpoint. The only difference is that the client id and secret are populated in the request body instead of the Authorization header.

Example authorization_code grant request body:

{
  "grant_type": "authorization_code",
  "authorization_code": "wac_widen_wQxhWkVHtsPx0Asj",
  "client_id": "MOwok9otudU3cHVlkbBAC1hsbOk3vgmoyEjUJMRu.app.widen.com",
  "client_secret": "p8xsXJfBPqfkEE1IT3MVZYXtrvxTp1xXdaHjWwuS"
}

Refresh token grant

The refresh token grant type is now supported and only available in v2.0. If you’re unfamiliar with refresh tokens, we suggest reading more about them in this blog post.

Things to note about our implementation:

Refresh tokens are enabled per integration and can currently only be enabled on new integrations.
- If you’d like to enable this feature, please contact the Acquia DAM Customer Support team for assistance.
- After refresh tokens are enabled for an integration, two new fields will be returned during any access token generation request:
  - refresh_token — The refresh token that can be exchanged for a new access token and refresh token in the future.
  - expires_in — The lifetime, in seconds, of the generated access token.
Refresh tokens expire after 6 months.
Access tokens generated via a refresh token expire after 8 hours.
Upon using a refresh token, it and all prior access tokens related to the supplied refresh token are invalidated.
- If a refresh token is used more than once, all access tokens and refresh tokens associated with the initial authorization will be invalidated.

Example refresh_token grant request body:

{
  "grant_type": "refresh_token",
  "refresh_token": "wrt_widen_7cWhrsuc0l56756L",
  "client_id": "MOwok9otudU3cHVlkbBAC1hsbOk3vgmoyEjUJMRu.app.widen.com",
  "client_secret": "p8xsXJfBPqfkEE1IT3MVZYXtrvxTp1xXdaHjWwuS"
}

For further documentation on this new endpoint, please visit our V2 API documentation.

Access token invalidation

Access tokens can be invalidated via the following endpoint:

DELETE /v2/oauth/access-token
- The access token supplied via the authorization header will be invalidated.

New OAuth allow access page

Our OAuth allow access page has been redesigned to be more user friendly. It will remain at the same URL and support the same query parameters; therefore, no changes will need to be made to existing integrations.

Example:

https://mysite.widencollective.com/allowaccess
?client_id=myclientid.app.widen.com
&redirect_uri=http://myredirecturl.com
&state=xyz123

Authorization codes generated via the new page are compatible with both the v1.0 and v2.0 of the API.

For further documentation on this page, please visit our V2 API documentation.

New token formats

As you may have noticed, tokens have taken on a new format. We designed them to be easily read and safe from HTTP encoding mishaps. They’re also compatible with both v1.0 and v2.0 API endpoints.

Tokens consist of three specific values joined by an underscore (_).

The first value is what we refer to as the token type. This prefix helps identify the type of token you may have, and will also easily allow Acquia DAM to perform secret scanning in public areas.

The token types are: